feat: add prepared trace bundles

docs/configuration.md

@@ -967,3 +967,10 @@ Invalid configuration will produce clear error messages with suggestions for fix
    - Monitor kernel memory usage when using large ringbuf sizes
    - Use smaller `proc_module_offsets_max_entries` for single-process debugging
    - Increase buffer size for high-frequency tracing scenarios
+
+## Prepared trace commands
+
+`ghostscope prepare -t TARGET --script-file SCRIPT -o BUNDLE` compiles without
+BPF privileges. `ghostscope run-bundle BUNDLE -p PID` uses the saved compilation
+configuration and skips DWARF parsing and LLVM codegen. See
+[Prepared trace bundles](prepared-traces.md) for runtime requirements and limits.

docs/prepared-traces.md

@@ -0,0 +1,74 @@
+# Prepared trace bundles
+
+Prepare a trace once, then attach the saved eBPF programs to a running process
+without repeating DWARF parsing or LLVM code generation:
+
+```bash
+ghostscope prepare -t /path/to/app --script-file trace.gs -o trace.gsb
+sudo ghostscope run-bundle trace.gsb -p <PID>
+```
+
+`prepare` runs as an ordinary user. It reads the target and its debug information,
+resolves the script, and writes a new bundle. It does not probe BPF kernel
+capabilities, load BPF programs, attach uprobes, start sysmon, or create bpffs pins.
+An existing output file is never overwritten. Compilation must succeed for every
+resolved target; partial compilations are not published as bundles.
+
+`run-bundle` verifies the bundle format, GhostScope version, native architecture,
+target file SHA-256, module cookie, and the target's executable mapping in the
+specified process. It then checks kernel capabilities, initializes runtime module
+offsets, and attaches the saved probes. Event decoding, output-loss reporting,
+and signal handling use the normal CLI runtime. There is no fallback to DWARF
+loading or recompilation.
+
+## First milestone scope
+
+- CLI scripts targeting one executable or shared-library module in a host process.
+- Process-scoped multi-uprobe support is required on the runtime kernel, including
+  correct coverage of worker threads. Preparation does not require this support
+  on its own kernel.
+- `bt` / `backtrace`, including nested uses, are rejected during preparation.
+- `$input_pid` is unavailable during preparation. `$pid` and `$tid` are read at
+  probe time and use host PID semantics. Container PID namespaces are not yet
+  supported by `run-bundle`.
+- RingBuf is the default event transport. To prepare for PerfEventArray, use
+  `--config` with `[ebpf].force_perf_event_array = true`. Sleepable uprobes can
+  also be selected in the preparation config and require compatible runtime
+  capabilities. The consumer never silently changes the compiled backend.
+
+## Debug files, identity, and configuration
+
+`prepare` accepts `--config` and `--debug-file`, using the normal debug-file
+matching rules. The bundle stores its script, compilation configuration, probe
+attachment offsets, eBPF objects, and event-decoding type/context tables. Debug
+files and source files are not required by `run-bundle`.
+
+The target binary must remain byte-for-byte identical. In particular, strip or
+otherwise transform the binary **before** preparation, not afterwards. Removing
+a separate debug file after preparation is supported. To use an identical target
+at another location, pass `run-bundle ... -t /new/path/to/app`; its module cookie
+must also match. A target without an ELF build ID must retain its filesystem
+identity, so copying it to a different inode requires preparing another bundle.
+
+Bundles use a versioned JSON format and are limited to 64 MiB. Treat a bundle as
+executable code: run only artifacts from a trusted preparation workflow. The
+identity checks establish which target it was prepared for, not who produced it.
+Reprepare after changing the target, script, compilation configuration, or
+GhostScope version. Bundle schema changes also require repreparation.
+
+The runtime uses the saved eBPF configuration rather than the current user's
+configuration file. `--script-output pretty|plain|jsonl` and `--no-status` control
+runtime presentation.
+
+## Measuring startup cost
+
+Preparation reports its compilation time; `run-bundle` reports time to attachment
+unless `--no-status` is set. Target hashing, ELF mapping discovery, kernel
+capability checks, and BPF verification/loading still occur at runtime. This is
+not a zero-cost attach path.
+
+The `prepared_bundle_execution` e2e tests compare normal and prepared startup on
+a small C fixture with separate DWARF, verify reuse across PIDs and worker-thread
+coverage, and remove the debug file before running the bundle. Timing is reported
+without a brittle pass/fail threshold. Measure representative production binaries
+before extrapolating the speedup to large debug-info workloads.

docs/roadmap.md

@@ -48,3 +48,7 @@ GhostScope is still evolving quickly. The milestones below are ordered from “s
 - Typical scenario: sources and debug info live in the cloud, while binaries run on test rigs or local hosts.
 - Goal: keep GhostScope’s TUI on the control side and run the eBPF agent on the target machine, similar to `gdb`/`gdbserver`.
 - This will come after the core functionality stabilizes to avoid diluting near-term focus.
+
+## Prepared trace bundles
+- The CLI `prepare` / `run-bundle` first milestone moves DWARF parsing and LLVM codegen out of repeated attach operations for host processes. See [Prepared trace bundles](prepared-traces.md) for compatibility requirements and current exclusions.
+- Follow-up work includes runtime PID-namespace binding and module-level CFI/symbol providers for backtraces.

docs/zh/configuration.md

@@ -922,3 +922,9 @@ GhostScope 在启动时验证配置：
    - 使用大缓冲区时监控内核内存使用情况
    - 单进程调试时使用较小的 `proc_module_offsets_max_entries`
    - 高频跟踪场景下增加缓冲区大小
+
+## 预编译 trace 命令
+
+`ghostscope prepare -t TARGET --script-file SCRIPT -o BUNDLE` 无需 BPF 权限即可编译。
+`ghostscope run-bundle BUNDLE -p PID` 使用保存的编译配置，跳过 DWARF 解析和 LLVM 编译。
+运行要求和当前限制见[预编译 trace bundle](prepared-traces.md)。

docs/zh/prepared-traces.md

@@ -0,0 +1,43 @@
+# 预编译 trace bundle
+
+先以普通用户编译，再将保存的 eBPF 程序附加到运行中的进程：
+
+```bash
+ghostscope prepare -t /path/to/app --script-file trace.gs -o trace.gsb
+sudo ghostscope run-bundle trace.gsb -p <PID>
+```
+
+`prepare` 不需要 BPF 权限，不探测内核 BPF 能力，不加载或附加探针，不启动
+sysmon，也不写入 bpffs。所有目标必须编译成功，输出文件已存在时会报错，避免覆盖。
+
+`run-bundle` 校验格式版本、GhostScope 版本、本机架构、目标文件 SHA-256、模块
+cookie，以及该文件在指定 PID 中的可执行映射。之后检查内核能力、初始化运行时
+模块偏移并附加保存的程序，复用普通 CLI 的事件输出、丢失计数和退出清理。
+不会回退到 DWARF 解析或 LLVM 编译。
+
+首版范围：
+
+- 单个可执行文件或共享库模块，目标必须是宿主机进程。
+- 运行内核需要支持进程级 multi-uprobe，包括工作线程；准备机器不需要该能力。
+- 暂不支持 `bt` / `backtrace`、`$input_pid` 或容器 PID namespace。
+- `$pid` / `$tid` 在探针执行时读取，使用宿主机 PID 语义。
+- 默认使用 RingBuf。可在准备时通过 `--config` 选择 PerfEventArray 或 sleepable
+  uprobes；运行内核必须支持保存的配置，不会自动切换后端。
+
+准备时可用 `--debug-file` 指定独立调试文件，仍执行通常的身份校验。
+准备后可以移除独立调试文件，但目标二进制必须逐字节一致；strip 等处理应在
+准备之前完成。可用 `run-bundle ... -t /new/path/to/app` 指定相同目标的新路径。
+没有 ELF build ID 的目标必须保留原来的文件身份，复制到其他 inode 后需要重新准备。
+
+bundle 是有版本的 JSON 文件，上限为 64 MiB，包含脚本、编译配置、探针偏移、
+eBPF 对象及解码上下文。应像可执行文件一样，仅运行可信来源的 bundle。
+目标身份校验不等于来源认证。目标、脚本、编译配置、GhostScope 版本或 bundle
+格式变化后，应重新准备。
+
+运行时使用 bundle 保存的 eBPF 配置，不读取当前用户的配置文件。
+可用 `--script-output pretty|plain|jsonl` 和 `--no-status` 控制输出。
+
+准备和附加阶段会报告耗时。运行阶段仍需目标校验、ELF 映射发现、内核能力检测和
+BPF 验证/加载。测试中的小型 C fixture 会比较普通启动与 bundle 启动，并验证移除
+调试文件后的读取、跨 PID 复用及线程覆盖；不使用容易波动的耗时阈值。
+生产环境收益应使用有代表性的目标另行测量。

docs/zh/roadmap.md

@@ -48,3 +48,7 @@ GhostScope 仍处在快速演进阶段，以下里程碑按照“优先修补基
 - 典型场景：代码与调试信息在云端，目标二进制运行在测试机或本地。
 - 规划让 GhostScope TUI 仅运行在控制端，eBPF Agent 独立驻留在目标主机，参考 `gdb/gdbserver` 模式。
 - 待核心能力稳定后再启动该特性，以免分散目前的开发精力。
+
+## 预编译 trace bundle
+- CLI `prepare` / `run-bundle` 首版将宿主机进程重复附加时的 DWARF 解析与 LLVM 编译前移。兼容要求和当前限制见[预编译 trace bundle](prepared-traces.md)。
+- 后续支持运行时 PID namespace 绑定，以及用于 backtrace 的模块级 CFI/符号提供器。