Add managed runtime accounting and probe APIs

[yiguodev]

Summary

• use outbound tags as share names and report real parsing counts
• add build-only validation, isolated route checks, and batch delay/location probes
• persist current-session inbound traffic and expose saved snapshots through an authenticated loopback HTTP endpoint
• record reproducible native build inputs and keep runtime snapshot models internal
• update the typed Invoke contract to API v4

Validation

• go test ./... -count=1
• git diff --check

[Copilot]

🔵 Needs a closer look

It introduces a broad API version bump and significant runtime/probing/persistence behavior changes across many subsystems that warrant final human verification.

Pull request overview

This PR expands libXray’s capabilities around draft validation/probing and managed runtime accounting, while updating the typed Invoke wire contract to API v4 and aligning documentation accordingly.

Changes:

• Add managed runtime accounting: periodic persistence of inbound counters and an optional authenticated loopback HTTP endpoint for reading the saved snapshot.
• Add/extend draft operations: build-only validation, isolated route checking, URL probing, and optional location probing for pingBatch.
• Update share parsing/export behavior (use outbound tag as the node name) and introduce build-input metadata recording for reproducible builds.

File summaries

File	Description
xray/xray.go	Adds managed runtime lifecycle alongside the managed core instance (start/stop integration).
xray/xray_test.go	Adds coverage ensuring temporary operations reject overlap with an active managed instance.
xray/validation.go	Introduces build-only config validation and overlap rejection for testXray execution.
xray/runtime.go	Implements runtime snapshot sampling, persistence, and ownership locking.
xray/runtime_test.go	Adds tests for snapshot semantics (raw counters, save behavior, ownership, restart behavior).
xray/runtime_http.go	Implements authenticated loopback HTTP snapshot serving with timeouts and header constraints.
xray/runtime_http_test.go	Tests auth, snapshot serving behavior, symlink rejection behavior, and concurrent reads.
xray/runtime_file.go	Adds non-Windows file locking and atomic replace with directory sync.
xray/runtime_file_windows.go	Adds Windows file locking and atomic replace semantics via Win32 APIs.
xray/probe.go	Adds a draft URL probe that routes/dials through a constructed draft instance without listening.
xray/probe_test.go	Tests probe routing/DNS behavior and URL safety constraints.
xray/ping_location_test.go	Adds tests for PingBatch location probing and probeLocation behavior.
xray/ping_batch.go	Extends ping batch results with optional location probing, and preserves latency behavior.
xray/check_route.go	Adds draft route checking using the real Router without starting the instance or dispatching the target.
xray/check_route_test.go	Adds tests for route evidence correctness, side-effect avoidance, timeouts, and invalid inputs.
share/xray_json.go	Switches outbound display naming to tag (instead of sendThrough).
share/validate_outbound.go	Removes legacy sendThrough nulling since it’s no longer used as name metadata.
share/parse_stats.go	Adds stats-enabled share parsing that returns usable/failed counts plus projected config.
share/parse_stats_test.go	Adds tests for candidate counting, error redaction, and legacy config equivalence.
share/parse_share_test.go	Updates expectations to reflect tag-based node naming and sendThrough preservation.
share/marshal_share.go	Refactors marshal to return projected count and support stats mode.
share/marshal_share_test.go	Updates expectations for tag vs sendThrough semantics in projected outputs.
share/generate_share_test.go	Updates tests to ensure outbound naming ignores sendThrough for node name selection.
share/clash_meta_test.go	Updates tests to validate tag is used for Clash-derived node names.
share/age.go	Refactors age decryption path to return plaintext + encrypted flag, enabling stats mode reuse.
readme/README.zh_CN.md	Updates Chinese docs for API v4, probes, ping location, runtime accounting, and build metadata.
README.md	Updates English docs for API v4, probes, ping location, runtime accounting, and build metadata.
invoke.go	Wires new API v4 methods/fields: stats conversion, ping location, testXray buildOnly/url probe, checkRoute, runtime metadata.
invoke_test.go	Adds tests for build-only semantics, checkRoute wiring/shape, runtime metadata typing, API version updates.
invoke_probes_test.go	Adds tests for share stats response shape, URL probe behavior, and ping location field encoding.
invoke_model.go	Updates typed Invoke contract to API v4 and adds new request/response models for new features.
desktop_bin/main.go	Adds optional -runtime host metadata file support for the desktop session core.
desktop_bin/main_test.go	Extends option parsing tests to cover the new -runtime flag.
build/test_build_metadata.py	Adds unit tests for build input metadata capture behavior and failure modes.
build/app/build.py	Implements build input metadata recording (commit, dirty state, modules, hashes, gomobile details).
AGENTS.md	Updates the repo’s documented API contract and runtime semantics to v4 and new features.
.gitignore	Ignores generated build input metadata JSON files.

Review details

• Files reviewed: 36/37 changed files
• Comments generated: 3
• Review effort level: Lite

---

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

[Copilot]

🟡 Changes recommended

The new test xray/runtime_http_test.go uses sync.WaitGroup.Go(...), which is not a standard sync.WaitGroup API and will fail to compile unless corrected.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 36/37 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It introduces broad, cross-cutting API/runtime/build changes (including a wire-contract version bump) that warrant careful human validation despite strong test coverage.

Review details

• Files reviewed: 41/42 changed files
• Comments generated: 1
• Review effort level: Lite