✨ feat: improve v0.3.1 agent investigation

AGENTS.md

@@ -6,6 +6,9 @@
 - `README.md` and `docs/` describe released behavior. Rewrite stale sections in
   place when behavior changes; do not append historical caveats or parallel
   inventories.
+- Treat user reports and external reviews as evidence to investigate, not as
+  implemented fact. Verify claims about bounds, clocks, filtering, lifecycle,
+  and errors against code and tests before documenting or changing them.
 
 ## Boundaries
 
@@ -33,8 +36,25 @@
 ## Agent workflow
 
 - Follow `skills/xprobe-measure-latency/SKILL.md` for measurement tasks.
-- Use `doctor`, `discover`, `validate`, then one bounded `measure` call.
-- Read evidence pairs and all quality fields before interpreting latency.
+- For an unknown workload, progress from readiness and baseline through a short
+  survey artifact, evidence-based selector narrowing, validation, and one
+  bounded measurement per stated hypothesis. Do not guess selectors.
+- Read evidence pairs, artifact analysis, stream identity, collection quality,
+  and profiler overhead before interpreting latency. Summed concurrent GPU
+  duration is not wall time.
+- Keep reusable analysis deterministic and bundled with the Skill. Keep model
+  orchestration in the caller rather than adding CLI commands or a service.
+
+## Release discipline
+
+- Start post-release work on a dedicated feature or fix branch. Rebase pull
+  requests into `master`; do not create merge commits.
+- Build Linux release artifacts on Ubuntu 22.04 and enforce a GLIBC_2.34 ceiling
+  for the CLI and every shipped Agent ELF.
+- A release is complete only after downloading the public archive, checking its
+  digest, testing installation, and inspecting all shipped ELF compatibility.
+- Retry CI only when logs identify a transient infrastructure failure. Preserve
+  real compiler, test, packaging, and compatibility failures for diagnosis.
 
 ## Verification
 
@@ -44,5 +64,7 @@
 - Run `just test-injection-live` for injection or agent lifecycle changes.
 - Run `just test-multisource-live` for host/GPU orchestration changes.
 - Run `just test-agent-contract` for CLI, schema, docs, or Skill changes.
+- Test bundled Skill scripts with deterministic fixtures and include them in
+  `just test-agent-contract`.
 - Run `just benchmark-gpu` for callback hot-path changes.
 - Use emoji conventional commits, for example `🐛 fix: restore target registers`.

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.20)
 
-project(xprobe VERSION 0.3.0 LANGUAGES C)
+project(xprobe VERSION 0.3.1 LANGUAGES C)
 
 include(CTest)
 

Cargo.toml

@@ -10,7 +10,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/itdevwu/xprobe"

README.md

@@ -18,7 +18,7 @@ contracts, explicit correlation quality, and no daemon or server lifecycle.
 
 ```bash
 curl --proto '=https' --tlsv1.2 -fsSL \
-  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.0/install.sh | sh
+  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.1/install.sh | sh
 ```
 
 This installs the released CLI and CUDA 12/13 Agents under `~/.local`. xprobe
@@ -32,13 +32,15 @@ Install the version-matched Skill with the open Agent Skills CLI:
 
 ```bash
 npx skills@1 add \
-  https://github.com/itdevwu/xprobe/tree/v0.3.0/skills/xprobe-measure-latency \
+  https://github.com/itdevwu/xprobe/tree/v0.3.1/skills/xprobe-measure-latency \
   --global
 ```
 
 The installer detects Codex, Claude Code, Cursor, and other compatible agents.
 Node.js is only needed for this Skill installation, not for xprobe itself. Set
 `DISABLE_TELEMETRY=1` when anonymous `skills` CLI telemetry is not wanted.
+The Skill guides a short survey, derives selectors from trace evidence, and
+includes a deterministic multi-stream JSONL analyzer.
 
 ## Measure
 
@@ -91,7 +93,7 @@ for safe reactivation.
 
 ## Support
 
-| Surface | 0.3.0 support |
+| Surface | 0.3.1 support |
 | --- | --- |
 | OS/architecture | Linux x86_64, glibc 2.34 or newer |
 | Host events | ELF function entry/return through PID-scoped uprobes |

SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported Versions
+
+xprobe is a pre-1.0 project. Security fixes are provided for the latest release
+only. Reproduce a report against the latest release or the current `master`
+branch when possible.
+
+| Version | Supported |
+| --- | --- |
+| Latest release | Yes |
+| Older releases | No |
+
+## Reporting a Vulnerability
+
+Report suspected vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/itdevwu/xprobe/security/advisories/new).
+Do not open a public issue for an undisclosed vulnerability.
+
+Include the affected xprobe version, operating system and kernel, relevant
+permission and namespace configuration, reproduction steps, observed impact,
+and whether the target process recovered cleanly. Remove application secrets,
+captured payloads, and other unrelated sensitive data from the report.
+
+This project is maintained independently and does not promise a response SLA.
+Reports will be assessed as time permits. Please allow a reasonable period for
+triage and remediation before public disclosure.
+
+## Trust Boundary
+
+xprobe uses eBPF/perf and ptrace capabilities granted by Linux. A live CUDA
+measurement may inject a CUPTI Agent into a process that the invoking user is
+already permitted to trace. The Agent remains mapped after collection and is
+disabled logically. These documented operations intentionally modify target
+state and require elevated access in many environments.
+
+Security boundaries still apply around which process is selected, which Linux
+credentials and namespaces authorize access, what data is collected, how target
+state is restored, and who can read or control local artifacts and Agent sockets.
+
+## Scope
+
+Examples of security issues include:
+
+- accessing or modifying a process outside the invoking user's Linux authority;
+- PID reuse or identity-check failures that attach to a different process;
+- failed attach or injection cleanup that does not restore target execution
+  state;
+- Agent sockets, trace artifacts, or installed files with unsafe permissions;
+- collection or exposure of sensitive target data beyond the documented event
+  contract;
+- package or installer behavior that violates the documented integrity checks.
+
+Ordinary profiling overhead, inaccurate measurements without a security impact,
+expected mutation disclosed by `validate` and `measure`, and behavior on an
+unsupported release are not security vulnerabilities by themselves.

docs/agent-integration.md

@@ -17,15 +17,19 @@ installer's responsibility:
 
 ```bash
 npx skills@1 add \
-  https://github.com/itdevwu/xprobe/tree/v0.3.0/skills/xprobe-measure-latency \
+  https://github.com/itdevwu/xprobe/tree/v0.3.1/skills/xprobe-measure-latency \
   --global
 ```
 
 For automation, add `--agent codex|claude-code|cursor --copy --yes`. Omit
 `--global` for repository-scoped installation. The Skill is self-contained;
-install its whole directory so its references and example remain available.
+install its whole directory so its references, examples, and analysis script
+remain available.
 
-The xprobe repository tests installation with `skills` CLI 1.5.20 in isolated
+The Skill moves from a short survey artifact to evidence-based selector
+narrowing and includes `scripts/analyze_trace.py` for deterministic kernel,
+copy, overlap, stream, and gap summaries. The xprobe repository tests
+installation with `skills` CLI 1.5.20 in isolated
 home directories. This pinned test protects released behavior while the
 documented `skills@1` selector receives compatible path updates.
 
@@ -38,8 +42,9 @@ just test-skill-install
 
 The test requires the visible command set to be exactly `doctor`, `discover`,
 `validate`, and `measure`. It invokes the first three in strict JSON mode,
-checks injection requirements, verifies schemas, and checks that the Skill uses
-only the four-command bounded workflow and inspects result quality/evidence.
+checks injection requirements, verifies schemas, exercises the bundled trace
+analyzer, and checks that the Skill uses only the four-command bounded workflow
+and inspects result quality/evidence.
 The installation test uses the real third-party CLI with telemetry disabled and
 verifies byte-for-byte copies for Codex, Claude Code, and Cursor.
 

docs/cli-contract.md

@@ -1,6 +1,6 @@
 # CLI contract
 
-xprobe 0.3.0 exposes exactly four public commands: `doctor`, `discover`,
+xprobe 0.3.1 exposes exactly four public commands: `doctor`, `discover`,
 `validate`, and `measure`.
 
 ## Common behavior

docs/installation.md

@@ -11,7 +11,7 @@ The versioned bootstrap installs to `~/.local` without root access:
 
 ```bash
 curl --proto '=https' --tlsv1.2 -fsSL \
-  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.0/install.sh | sh
+  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.1/install.sh | sh
 ```
 
 The bootstrap downloads the release archive and its SHA256 file, verifies the
@@ -30,7 +30,7 @@ prefix, download the script and pass `--prefix`:
 
 ```bash
 curl --proto '=https' --tlsv1.2 -fsSLO \
-  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.0/install.sh
+  https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.1/install.sh
 sh install.sh --prefix /opt/xprobe
 ```
 
@@ -42,7 +42,7 @@ script with `sudo`. The installer never elevates privileges itself.
 For a fully explicit archive workflow:
 
 ```bash
-version=0.3.0
+version=0.3.1
 base=https://github.com/itdevwu/xprobe/releases/download/v$version
 archive=xprobe-$version-linux-x86_64.tar.gz
 
@@ -76,7 +76,7 @@ version-matched Skill:
 
 ```bash
 npx skills@1 add \
-  https://github.com/itdevwu/xprobe/tree/v0.3.0/skills/xprobe-measure-latency \
+  https://github.com/itdevwu/xprobe/tree/v0.3.1/skills/xprobe-measure-latency \
   --global
 ```
 
@@ -85,7 +85,7 @@ installation names the target explicitly:
 
 ```bash
 DISABLE_TELEMETRY=1 npx --yes skills@1 add \
-  https://github.com/itdevwu/xprobe/tree/v0.3.0/skills/xprobe-measure-latency \
+  https://github.com/itdevwu/xprobe/tree/v0.3.1/skills/xprobe-measure-latency \
   --agent codex --global --copy --yes
 ```
 
@@ -95,8 +95,8 @@ an agent to execute commands with its granted permissions.
 
 Without Node.js, copy the complete `skills/xprobe-measure-latency` directory
 from the release archive into the Skill directory documented by the target
-agent. Do not copy only `SKILL.md`; its local references and example are part of
-the contract.
+agent. Do not copy only `SKILL.md`; its references, examples, and trace-analysis
+script are part of the contract.
 
 ## Runtime check
 

install.sh

@@ -2,7 +2,7 @@
 set -eu
 
 repository=${XPROBE_REPOSITORY:-itdevwu/xprobe}
-version=${XPROBE_VERSION:-0.3.0}
+version=${XPROBE_VERSION:-0.3.1}
 if [ -n "${XPROBE_PREFIX:-}" ]; then
   prefix=$XPROBE_PREFIX
 elif [ -n "${HOME:-}" ]; then
@@ -19,7 +19,7 @@ Install a released xprobe binary and its CUDA Agents.
 Usage: install.sh [--version VERSION] [--prefix DIR] [--uninstall]
 
 Options:
-  --version VERSION  Release to install (default: 0.3.0)
+  --version VERSION  Release to install (default: 0.3.1)
   --prefix DIR       Installation prefix (default: $HOME/.local)
   --uninstall        Remove xprobe from the selected prefix
   -h, --help         Show this help

justfile

@@ -18,9 +18,11 @@ test: build
     cargo test --workspace
     ctest --test-dir build --output-on-failure
     python3 tests/agent-contract/test_contract.py target/debug/xprobe
+    python3 tests/agent-contract/test_trace_analysis.py
 
 test-agent-contract: build
     python3 tests/agent-contract/test_contract.py target/debug/xprobe
+    python3 tests/agent-contract/test_trace_analysis.py
 
 test-skill-install:
     tests/agent-contract/test_skill_install.sh