feat(ingest): GitHub Copilot CLI collector via OTEL file exporter

CHANGELOG.md

@@ -4,6 +4,8 @@ Cross-package release notes for relayburn. Package changelogs contain package-le
 
 ## [Unreleased]
 
+- `burn ingest` collects GitHub Copilot CLI usage from the OpenTelemetry file exporter while `COPILOT_OTEL_FILE_EXPORTER_PATH` is set (the exporter file plus `~/.copilot/otel/*.jsonl`), recording per-API-call token usage as `copilot-cli` turns with usage-only fidelity; the opt-in setup is printed by the new `burn init copilot` helper.
+
 ## [4.1.0] - 2026-09-20
 
 - `burn measure` and `@relayburn/sdk.measureSession()` turn one explicit Claude Code, Codex, or OpenCode session source into a versioned per-model token/cost document without discovery or a ledger; incomplete and zero-turn inputs fail closed.

README.md

@@ -1,8 +1,9 @@
 ![relayburn](./burn-readme-banner.png)
 
 Understand how you're spending tokens in agent CLIs. Burn ingests Claude Code,
-Codex, and OpenCode session logs into a local ledger, then shows cost by model,
-provider, tool, file, workflow, agent, session, and overhead file.
+Codex, and OpenCode session logs — plus GitHub Copilot CLI's opt-in OTEL span
+export — into a local ledger, then shows cost by model, provider, tool, file,
+workflow, agent, session, and overhead file.
 
 ## Quick Start
 
@@ -29,6 +30,7 @@ Burn stores data under `~/.agentworkforce/burn/` by default. Set
 | [`burn flow`](#burn-flow) | Render a session's inference and subagent flow as Mermaid, SVG, or JSON. |
 | [`burn stamps`](#burn-stamps) | Export enrichment stamps as JSONL. |
 | [`burn ingest`](#burn-ingest) | Import existing or live session logs without wrapping the harness. |
+| [`burn init`](#collector-setup) | Print setup instructions for opt-in collectors (Copilot CLI). |
 | [`burn mcp-server`](#burn-mcp-server) | Expose read-only cost queries to an agent through stdio MCP. |
 | [`burn update`](#burn-update) | Check for releases, install an update, or configure automatic checks. |
 
@@ -205,7 +207,8 @@ Run `burn summary --by-provider` to discover model IDs present in your ledger.
 ## `burn ingest`
 
 Use `burn ingest` when sessions already exist, or when another process owns the
-harness spawn. Default mode scans Claude Code, Codex, and OpenCode stores once.
+harness spawn. Default mode scans Claude Code, Codex, and OpenCode stores once,
+plus the GitHub Copilot CLI OTEL export when it is enabled (see below).
 
 | Option | What it does |
 |---|---|
@@ -215,6 +218,24 @@ harness spawn. Default mode scans Claude Code, Codex, and OpenCode stores once.
 | `--hook claude` | Read one Claude Code hook payload from stdin and ingest its single transcript via the SDK fast-path. |
 | `--no-fsevents` | In watch mode, use polling instead of filesystem events. |
 
+### Collector setup
+
+**GitHub Copilot CLI** does not write a session log; it emits usage through its
+OpenTelemetry file exporter, and only when you opt in:
+
+```bash
+export COPILOT_OTEL_FILE_EXPORTER_PATH="$HOME/.copilot/otel/copilot.jsonl"
+```
+
+Add that to your shell rc file, restart the shell, and subsequent `copilot`
+sessions emit one JSONL span per API call, which `burn ingest` picks up
+automatically while the variable is set (the exporter file plus
+`~/.copilot/otel/*.jsonl`; without it Copilot ingest is a silent no-op).
+Nothing is recoverable retroactively — the exporter
+must be on before sessions are captured. Run `burn init copilot` to print these
+instructions. Coverage is usage-only: spans carry per-call token counts (input,
+output, cache read/write, reasoning) and the model, but no tool-call content.
+
 | Example | Result |
 |---|---|
 | `burn ingest` | Scan all known session stores once. |
@@ -497,7 +518,8 @@ burn ingest
 burn ingest --watch --interval 1000
 ```
 
-`burn ingest` scans Claude, Codex, and OpenCode stores once and uses the same
+`burn ingest` scans Claude, Codex, and OpenCode stores (plus the Copilot CLI
+OTEL export when enabled) once and uses the same
 cursor and dedup path as the reporting commands. `burn ingest --watch` keeps
 that scan loop running in the foreground.
 
@@ -521,7 +543,8 @@ the same session.
 ### What does `burn ingest` do?
 
 Each harness (Claude Code, Codex, OpenCode) writes its own session transcripts
-to disk in its own format. `burn ingest` reads those transcripts, normalizes
+to disk in its own format; GitHub Copilot CLI instead appends OTEL spans to the
+file named by `COPILOT_OTEL_FILE_EXPORTER_PATH` when that export is enabled. `burn ingest` reads those transcripts, normalizes
 them, and writes them into burn's local SQLite ledger so the query commands
 (`summary`, `hotspots`, `overhead`, `compare`) have something to read against.
 Three modes:

crates/relayburn-cli/src/cli.rs

@@ -126,6 +126,26 @@ pub enum Command {
 
     /// Check for, install, or configure `burn` self-updates.
     Update(UpdateArgs),
+
+    /// Print setup instructions for collectors that need opt-in
+    /// configuration (e.g. GitHub Copilot CLI's OTEL exporter).
+    Init(InitArgs),
+}
+
+/// Per-command flags for `burn init`.
+#[derive(Debug, Clone, ClapArgs)]
+pub struct InitArgs {
+    #[command(subcommand)]
+    pub action: InitAction,
+}
+
+/// Nested subcommand for `burn init`. Required — `burn init` on its own
+/// would have nothing to print.
+#[derive(Debug, Clone, Subcommand)]
+pub enum InitAction {
+    /// Print the COPILOT_OTEL_FILE_EXPORTER_PATH setup for the GitHub
+    /// Copilot CLI collector.
+    Copilot,
 }
 
 #[derive(Debug, Clone, ClapArgs)]

crates/relayburn-cli/src/commands/init.rs

@@ -0,0 +1,42 @@
+//! `burn init` — setup helpers for collectors that need opt-in
+//! configuration before burn can see their data.
+//!
+//! `burn init copilot` prints the exact `COPILOT_OTEL_FILE_EXPORTER_PATH`
+//! setup for the GitHub Copilot CLI collector (#14). It never touches the
+//! user's shell rc files — Copilot's exporter is opt-in and which rc file
+//! to edit is the user's call, so this just prints copy-pasteable lines.
+
+use crate::cli::InitArgs;
+
+/// Print the opt-in setup for one collector (`burn init copilot`).
+/// Read-only: never edits shell rc files, only prints copy-pasteable lines.
+pub fn run(args: InitArgs) -> i32 {
+    match args.action {
+        crate::cli::InitAction::Copilot => {
+            print!(
+                "GitHub Copilot CLI collector setup\n\
+                 \n\
+                 Copilot CLI only emits usage data when its OpenTelemetry file\n\
+                 exporter is enabled, and nothing is recoverable retroactively —\n\
+                 export must be on before sessions are captured.\n\
+                 \n\
+                 1. Point the exporter at a file burn scans:\n\
+                 \n\
+                 \x20   export COPILOT_OTEL_FILE_EXPORTER_PATH=\"$HOME/.copilot/otel/copilot.jsonl\"\n\
+                 \n\
+                 \x20   Add that line to your shell rc file (~/.zshrc, ~/.bashrc, …) so\n\
+                 \x20   new shells pick it up — burn ingest only scans Copilot\n\
+                 \x20   files while this variable is set. Any path works.\n\
+                 \n\
+                 2. Restart your shell (or `source` the rc file), then run Copilot CLI.\n\
+                 \n\
+                 3. Ingest as usual — `burn ingest` picks the spans up automatically.\n\
+                 \n\
+                 Coverage note: OTEL spans carry per-API-call token usage (input,\n\
+                 output, cache read/write, reasoning) and the model, but no tool-call\n\
+                 content, so Copilot turns report as usage-only fidelity.\n"
+            );
+            0
+        }
+    }
+}

crates/relayburn-cli/src/commands/mod.rs

@@ -23,6 +23,7 @@ pub mod flow;
 mod freshness;
 pub mod hotspots;
 pub mod ingest;
+pub mod init;
 pub mod mcp_server;
 pub mod measure;
 pub mod overhead;

crates/relayburn-cli/src/main.rs

@@ -60,6 +60,7 @@ fn dispatch(args: Args) -> i32 {
         Command::Ingest(args) => commands::ingest::run(&globals, args),
         Command::McpServer(args) => commands::mcp_server::run(&globals, args),
         Command::Update(args) => commands::update::run(&globals, args),
+        Command::Init(args) => commands::init::run(args),
     }
 }
 
@@ -87,5 +88,6 @@ fn command_name(command: &Command) -> &'static str {
         Command::Ingest(_) => "ingest",
         Command::McpServer(_) => "mcp-server",
         Command::Update(_) => "update",
+        Command::Init(_) => "init",
     }
 }

crates/relayburn-cli/tests/smoke.rs

@@ -36,6 +36,7 @@ const SUBCOMMANDS: &[&str] = &[
     "ingest",
     "mcp-server",
     "update",
+    "init",
 ];
 
 #[test]
@@ -437,6 +438,21 @@ fn json_mode_emits_error_envelope_on_argument_failure() {
     );
 }
 
+#[test]
+fn init_copilot_prints_otel_exporter_setup() {
+    let output = burn()
+        .args(["init", "copilot"])
+        .assert()
+        .success()
+        .get_output()
+        .clone();
+    let stdout = String::from_utf8(output.stdout).expect("stdout should be valid UTF-8");
+    assert!(
+        stdout.contains("COPILOT_OTEL_FILE_EXPORTER_PATH"),
+        "expected `init copilot` to print the exporter env var; got:\n{stdout}",
+    );
+}
+
 #[test]
 fn version_flag_exits_zero() {
     burn()

crates/relayburn-sdk/src/analyze/provider.rs

@@ -339,6 +339,7 @@ fn provider_from_source(source: SourceKind) -> String {
         SourceKind::Codex | SourceKind::OpenaiApi => "openai".into(),
         SourceKind::GeminiApi => "google".into(),
         SourceKind::Opencode => "opencode".into(),
+        SourceKind::CopilotCli => "github-copilot".into(),
     }
 }
 

crates/relayburn-sdk/src/ingest.rs

@@ -64,7 +64,8 @@ pub(crate) static TEST_GAP_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(()
 pub use gap::{restore_ingest_gap_writer, set_ingest_gap_writer};
 pub use ingest::{
     default_session_roots, ingest_all, ingest_claude_session, ingest_claude_transcript_path,
-    ingest_codex_sessions, ingest_opencode_sessions, IngestOptions, IngestReport, IngestRoots,
+    ingest_codex_sessions, ingest_copilot_sessions, ingest_opencode_sessions, IngestOptions,
+    IngestReport, IngestRoots,
 };
 pub use pending_stamps::{
     cleanup_stale_pending_stamps, write_pending_stamp, PendingStamp, PendingStampHarness,

crates/relayburn-sdk/src/ingest/cursors.rs

@@ -7,7 +7,8 @@
 //! ## Wire layout
 //!
 //! `{"files": {"<absolute path>": <cursor>}}`. The cursor variant is tagged
-//! by `kind`: `"claude" | "codex" | "opencode" | "opencode-stream"`. Field
+//! by `kind`: `"claude" | "codex" | "opencode" | "copilot" |
+//! "opencode-stream"`. Field
 //! names are camelCase to match the TS schema so a Rust ingest can pick up
 //! cursors a TS ingest wrote, and vice versa, during the migration.
 
@@ -68,6 +69,23 @@ pub struct OpencodeCursor {
     pub seen_message_ids: Vec<String>,
 }
 
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CopilotCursor {
+    pub inode: u64,
+    pub offset_bytes: u64,
+    pub mtime_ms: i64,
+    /// Next `turn_index` per session id, so a continued session keeps
+    /// numbering across incremental passes and exporter rotations.
+    #[serde(default)]
+    pub session_turn_counts: BTreeMap<String, u64>,
+    /// Trace ids known to contain a `chat` span; suppresses the
+    /// double-counting `invoke_agent` aggregate for those traces. Bounded
+    /// by the parser at a few thousand entries.
+    #[serde(default)]
+    pub chat_trace_ids: Vec<String>,
+}
+
 /// Tagged-union cursor variants. The Codex variant is heap-boxed because it
 /// carries a per-turn map and dwarfs the others — keeping the enum payload
 /// size sane keeps `Cursors` cheap to clone in the orchestration hot path.
@@ -77,6 +95,8 @@ pub enum FileCursor {
     Claude(ClaudeCursor),
     Codex(Box<CodexCursor>),
     Opencode(OpencodeCursor),
+    #[serde(rename = "copilot")]
+    Copilot(CopilotCursor),
     #[serde(rename = "opencode-stream")]
     OpencodeStream(Value),
 }

crates/relayburn-sdk/src/ingest/gap.rs

@@ -48,6 +48,7 @@ pub enum AdapterName {
     Claude,
     Codex,
     Opencode,
+    Copilot,
 }
 
 impl AdapterName {
@@ -56,6 +57,7 @@ impl AdapterName {
             AdapterName::Claude => "claude",
             AdapterName::Codex => "codex",
             AdapterName::Opencode => "opencode",
+            AdapterName::Copilot => "copilot",
         }
     }
 }

crates/relayburn-sdk/src/ingest/gap_warning_tests.rs

@@ -59,6 +59,7 @@ fn pinned_roots(tmp: &TempDir) -> IngestRoots {
         claude_projects_dir: Some(tmp.path().join("claude").join("projects")),
         codex_sessions_dir: Some(tmp.path().join("codex").join("sessions")),
         opencode_storage_dir: Some(tmp.path().join("opencode").join("storage")),
+        copilot_otel_files: Some(vec![]),
     }
 }