godmode-core 0.8.1

Core library for godmode: task graphs, session state, dispatch, and Claude Code plugin integrations.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
//! Read side of the godmode trace log.
//!
//! The log is `.ctx/godmode/traces/trace.jsonl`: an append-only, best-effort,
//! cross-process event stream written by Nushell hooks, Rust hooks, and the CLI
//! alike. This module turns those lines back into typed records and answers the
//! questions the `godmode trace` subcommands ask.
//!
//! # Why crux `Step`
//!
//! New lines are written in crux's canonical [`Step`] schema so the event
//! vocabulary is owned by crux rather than re-declared in godmode and Nushell
//! separately. `Step` is already serialisable, so the on-disk form and the
//! in-memory form are the same type.
//!
//! Two fields carry meaning that crux's own enums do not model, and both live
//! in `Step::metadata` — the extension point crux provides:
//!
//! * `phase` — `start` or `terminal`. A `Step` describes a *resolved* step, but
//!   a JSONL log records both halves of a lifecycle as separate lines. The
//!   unresolved-agent query depends on seeing the open half.
//! * `session_id` / `trace_id` / `slot` / `crate` — correlation fields.
//!
//! What this module deliberately does **not** do is wrap each line in a
//! `Crux<T>` envelope. `Crux<T>` models one replayable computation owned by one
//! process; this log is written by many short-lived processes that share
//! nothing but the file, and emitting is explicitly non-fatal. Enforcing a
//! resolved-value shape on a fire-and-forget audit line would be ceremony that
//! breaks the guarantee the hot path relies on. `session_trace` remains the
//! place `Crux<T>` belongs.

use std::collections::{BTreeMap, BTreeSet, HashSet};

use chrono::{DateTime, FixedOffset, Local};
use crux_runtime::types::step::{Step, StepKind, StepStatus};
use serde::Serialize;
use serde_json::Value;

/// Which half of a lifecycle a line represents.
///
/// Owned by [`trace_log`](crate::hooks::trace_log) because the writer defines
/// the vocabulary; this module only has to agree with it.
pub use crate::hooks::trace_log::Phase;

/// One trace line, normalised across both on-disk schemas.
#[derive(Debug, Clone)]
pub struct Record {
    /// Actor identity: skill name, agent id, or tool name.
    pub name: String,
    pub kind: StepKind,
    /// `None` while the lifecycle half is still open.
    pub status: Option<StepStatus>,
    pub phase: Phase,
    pub started_at: Option<DateTime<FixedOffset>>,
    pub duration_ms: Option<u64>,
    pub session_id: Option<String>,
    pub trace_id: Option<String>,
    /// Everything else the writer attached, including `slot`, `crate`,
    /// `exit_code`, and `stderr_tail`.
    pub metadata: BTreeMap<String, Value>,
    pub error: Option<String>,
}

impl Record {
    /// True when the record represents a failure: an errored step, or one that
    /// was rejected/blocked.
    pub fn is_failure(&self) -> bool {
        matches!(
            self.status,
            Some(StepStatus::Err) | Some(StepStatus::Rejected)
        )
    }

    /// True when the record opened a lifecycle that never closed.
    pub fn is_open(&self) -> bool {
        self.phase == Phase::Start
    }

    pub fn meta_str(&self, key: &str) -> Option<&str> {
        self.metadata.get(key).and_then(Value::as_str)
    }

    /// True when the record describes a dispatched agent rather than a skill
    /// or tool. crux spells this `Delegation`.
    pub fn is_agent(&self) -> bool {
        self.kind == StepKind::Delegation
    }

    /// True when the record is a branching decision. crux spells this `Branch`.
    pub fn is_decision(&self) -> bool {
        self.kind == StepKind::Branch
    }

    /// True when the record is a session lifecycle marker rather than an actor's step.
    ///
    /// Derived from `metadata["event"]`, which survives parsing because
    /// `from_legacy` strips `event`, `session_id`, and `ts` into `known`, leaves
    /// metadata empty, and reinserts `event` when the map comes back empty.
    pub fn is_marker(&self) -> bool {
        self.metadata
            .get("event")
            .and_then(Value::as_str)
            .is_some_and(is_session_marker)
    }
}

/// Per-skill duration rollup.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct SkillDuration {
    pub skill: String,
    pub runs: usize,
    pub avg_ms: u64,
    pub max_ms: u64,
}

/// Per-tool call count.
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ToolCount {
    pub tool: String,
    pub calls: usize,
}

/// Convergence status for one agent identity.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub enum AgentStatus {
    Complete,
    Blocked,
    Running,
}

impl AgentStatus {
    pub fn as_str(self) -> &'static str {
        match self {
            AgentStatus::Complete => "complete",
            AgentStatus::Blocked => "blocked",
            AgentStatus::Running => "running",
        }
    }
}

/// Aggregation behind `godmode trace stats`.
#[derive(Debug, Clone, Default)]
pub struct Stats {
    pub total_records: usize,
    pub distinct_sessions: usize,
    /// Distinct session ids that recorded at least one non-marker record.
    ///
    /// Distinct from [`Self::distinct_sessions`], which counts every id in the
    /// log. A session opened and rotated away without recording work is a real
    /// session but not an active one.
    pub active_sessions: usize,
    pub session_starts: usize,
    pub session_ends: usize,
    pub last_ts: Option<String>,
    pub last_at: Option<DateTime<FixedOffset>>,
    pub skill_durations: Vec<SkillDuration>,
    pub tool_counts: Vec<ToolCount>,
    pub agents: Vec<(String, AgentStatus)>,
    pub decision_count: usize,
    pub failure_count: usize,
}

/// Cross-session rollup behind `godmode trace summary`.
#[derive(Debug, Clone, PartialEq)]
pub struct SessionSummary {
    pub session_id: String,
    pub started: String,
    pub errors: usize,
    pub blocked: usize,
    pub complete: usize,
    pub decisions: usize,
    /// Agent identities whose `agent.start` has no terminal counterpart.
    pub unresolved: Vec<String>,
}

/// Parse a log body into records, skipping blank and unparseable lines.
///
/// A torn trailing line is expected whenever a writer is killed mid-append, so
/// one bad line must not cost the caller the rest of the file.
///
/// This module performs no I/O. Use [`trace_store::read_body`](crate::trace_store::read_body)
/// to obtain the text, then hand it here.
pub fn parse(body: &str) -> Vec<Record> {
    body.lines()
        .map(str::trim)
        .filter(|l| !l.is_empty())
        .filter_map(|l| serde_json::from_str::<Value>(l).ok())
        .map(record_from_value)
        .collect()
}

/// Project one JSON line onto [`Record`], accepting both schemas.
///
/// The `Crux` branch is a `Step` that already carries its phase in metadata.
/// The legacy branch maps the pre-0.7 `{event, ...}` vocabulary, so logs written
/// before the upgrade keep answering queries.
fn record_from_value(value: Value) -> Record {
    match serde_json::from_value::<Step>(value.clone()) {
        Ok(step) => from_step(step),
        Err(_) => from_legacy(value),
    }
}

fn from_step(step: Step) -> Record {
    // crux types `metadata` as a HashMap; `Record` uses a BTreeMap so rendering
    // and tests see a deterministic key order.
    let metadata: BTreeMap<String, Value> = step.metadata.into_iter().collect();
    let session_id = meta_string(&metadata, "session_id");
    let trace_id = meta_string(&metadata, "trace_id");
    let phase = match meta_string(&metadata, "phase").as_deref() {
        Some("start") => Phase::Start,
        _ => Phase::Terminal,
    };
    // `phase` is authoritative over `status` for an open step. crux has no
    // "pending" variant, so the writer fills `Ok` on a start line as a schema
    // formality; treating that as an outcome would make a still-running skill
    // indistinguishable from a finished one.
    let status = if phase == Phase::Start {
        None
    } else {
        Some(step.status)
    };

    Record {
        name: step.name,
        kind: step.kind,
        status,
        phase,
        started_at: Some(step.started_at.into()),
        duration_ms: Some(step.duration_ms),
        session_id,
        trace_id,
        metadata,
        error: step.error,
    }
}

fn from_legacy(value: Value) -> Record {
    let event = string_at(&value, "event").unwrap_or_default();
    let status = status_for_event(&event, &value);
    let kind = kind_for_event(&event);
    // A session lifecycle marker has no actor. Naming it after its own
    // `session_id` is what left `stats`' `name.is_empty()` marker test
    // unreachable — every marker carried an id, so `name` was never empty.
    let name = if is_session_marker(&event) {
        String::new()
    } else {
        string_at(&value, "skill")
            .or_else(|| string_at(&value, "agent_id"))
            .or_else(|| string_at(&value, "tool"))
            .or_else(|| string_at(&value, "session_id"))
            .unwrap_or_default()
    };
    let phase = if event.ends_with(".start") {
        Phase::Start
    } else {
        Phase::Terminal
    };

    let known = [
        "event",
        "skill",
        "agent_id",
        "tool",
        "session_id",
        "trace_id",
        "ts",
        "duration_ms",
        "reason",
        "failed",
        "kind",
        "value",
    ];
    // Everything the writer attached beyond the fields projected above survives
    // in metadata, so queries never have to know which schema produced a record.
    let mut metadata: BTreeMap<String, Value> = value
        .as_object()
        .map(|m| {
            m.iter()
                .filter(|(k, _)| !known.contains(&k.as_str()))
                .map(|(k, v)| (k.clone(), v.clone()))
                .collect()
        })
        .unwrap_or_default();
    if metadata.is_empty() && value.as_object().is_some() {
        metadata.insert("event".into(), Value::String(event.clone()));
    }

    Record {
        name,
        kind,
        status,
        phase,
        started_at: string_at(&value, "ts").and_then(|s| DateTime::parse_from_rfc3339(&s).ok()),
        duration_ms: value.get("duration_ms").and_then(Value::as_u64),
        session_id: string_at(&value, "session_id"),
        trace_id: string_at(&value, "trace_id"),
        metadata,
        error: string_at(&value, "reason"),
    }
}

fn is_session_marker(event: &str) -> bool {
    matches!(event, "session.start" | "session.end")
}

fn kind_for_event(event: &str) -> StepKind {
    match event {
        "agent.start" | "agent.complete" | "agent.blocked" => StepKind::Delegation,
        "decision" => StepKind::Branch,
        _ => StepKind::Plain,
    }
}

fn status_for_event(event: &str, value: &Value) -> Option<StepStatus> {
    match event {
        "skill.start" | "agent.start" => None,
        "skill.error" => Some(StepStatus::Err),
        "agent.blocked" => Some(StepStatus::Rejected),
        "tool.use" => Some(if value.get("failed") == Some(&Value::Bool(true)) {
            StepStatus::Err
        } else {
            StepStatus::Ok
        }),
        _ => Some(StepStatus::Ok),
    }
}

fn string_at(value: &Value, key: &str) -> Option<String> {
    value.get(key).and_then(Value::as_str).map(str::to_string)
}

fn meta_string(metadata: &BTreeMap<String, Value>, key: &str) -> Option<String> {
    metadata
        .get(key)
        .and_then(Value::as_str)
        .map(str::to_string)
}

/// The most recent `n` records, in file order.
pub fn tail(records: &[Record], n: usize) -> Vec<&Record> {
    let start = records.len().saturating_sub(n);
    records[start..].iter().collect()
}

/// Every failure, in file order.
pub fn failures(records: &[Record]) -> Vec<&Record> {
    records.iter().filter(|r| r.is_failure()).collect()
}

/// Distinct session ids, in first-seen order.
pub fn session_ids(records: &[Record]) -> Vec<String> {
    let mut out: Vec<String> = Vec::new();
    for r in records {
        if let Some(sid) = &r.session_id
            && !out.contains(sid)
        {
            out.push(sid.clone());
        }
    }
    out
}

/// Agent identities dispatched with no terminal counterpart.
///
/// The terminal that resolves an agent is `agent.complete` or `agent.blocked`,
/// both of which carry the same `agent_id` as the opening `agent.start`.
pub fn unresolved_agents(records: &[&Record]) -> Vec<String> {
    let closed: HashSet<&str> = records
        .iter()
        .filter(|r| r.is_agent() && !r.is_open())
        .map(|r| r.name.as_str())
        .collect();

    // Order-independent: a terminal line that lands after its opening line must
    // still resolve it, so membership is tested against the whole set rather
    // than consumed positionally.
    let mut out: Vec<String> = Vec::new();
    for r in records.iter().filter(|r| r.is_agent() && r.is_open()) {
        if !closed.contains(r.name.as_str()) && !out.contains(&r.name) {
            out.push(r.name.clone());
        }
    }
    out
}

/// Roll up a single session.
pub fn summarise_session(session_id: &str, records: &[&Record]) -> SessionSummary {
    let starts: Vec<&&Record> = records.iter().filter(|r| r.is_open()).collect();
    SessionSummary {
        session_id: session_id.to_string(),
        started: starts
            .first()
            .and_then(|r| r.started_at)
            .map(|t| t.to_rfc3339())
            .unwrap_or_default(),
        errors: records
            .iter()
            .filter(|r| r.status == Some(StepStatus::Err))
            .count(),
        blocked: records
            .iter()
            .filter(|r| r.status == Some(StepStatus::Rejected))
            .count(),
        complete: records
            .iter()
            .filter(|r| r.is_agent() && !r.is_open() && r.status == Some(StepStatus::Ok))
            .count(),
        decisions: records.iter().filter(|r| r.is_decision()).count(),
        unresolved: unresolved_agents(records),
    }
}

/// Aggregate a record set.
pub fn stats(records: &[Record]) -> Stats {
    let mut durations: BTreeMap<String, Vec<u64>> = BTreeMap::new();
    let mut tools: BTreeMap<String, usize> = BTreeMap::new();

    for r in records {
        match (r.is_open(), r.duration_ms) {
            (false, Some(ms)) if !r.name.is_empty() && !r.is_agent() && !r.is_decision() => {
                durations.entry(r.name.clone()).or_default().push(ms);
            }
            _ => {}
        }
        if !r.is_open() && r.phase == Phase::Terminal && r.meta_str("tool").is_some() {
            *tools
                .entry(
                    r.meta_str("tool")
                        .map(str::to_string)
                        .unwrap_or_else(|| r.name.clone()),
                )
                .or_default() += 1;
        }
    }

    let mut agents: Vec<(String, AgentStatus)> = Vec::new();
    for id in records
        .iter()
        .filter(|r| r.is_agent() && r.is_open())
        .map(|r| r.name.clone())
    {
        if agents.iter().any(|(n, _)| *n == id) {
            continue;
        }
        let scoped: Vec<&Record> = records.iter().filter(|r| r.is_agent()).collect();
        let status = if scoped
            .iter()
            .any(|r| r.status == Some(StepStatus::Rejected) && r.name == id)
        {
            AgentStatus::Blocked
        } else if scoped
            .iter()
            .any(|r| r.status == Some(StepStatus::Ok) && r.name == id)
        {
            AgentStatus::Complete
        } else {
            AgentStatus::Running
        };
        agents.push((id, status));
    }

    let mut active: BTreeSet<&str> = BTreeSet::new();
    for r in records {
        if let Some(sid) = r.session_id.as_deref()
            && !r.is_marker()
        {
            active.insert(sid);
        }
    }

    let last = records.last();
    let mut skill_durations: Vec<SkillDuration> = durations
        .into_iter()
        .map(|(skill, runs)| {
            let sum: u64 = runs.iter().sum();
            let max = runs.iter().copied().max().unwrap_or_default();
            SkillDuration {
                skill,
                runs: runs.len(),
                avg_ms: sum / runs.len() as u64,
                max_ms: max,
            }
        })
        .collect();
    skill_durations.sort_by(|a, b| a.skill.cmp(&b.skill));

    let mut tool_counts: Vec<ToolCount> = tools
        .into_iter()
        .map(|(tool, calls)| ToolCount { tool, calls })
        .collect();
    tool_counts.sort_by(|a, b| b.calls.cmp(&a.calls).then(a.tool.cmp(&b.tool)));

    Stats {
        total_records: records.len(),
        distinct_sessions: session_ids(records).len(),
        active_sessions: active.len(),
        session_starts: records
            .iter()
            .filter(|r| r.is_open() && r.is_marker())
            .count(),
        session_ends: records
            .iter()
            .filter(|r| !r.is_open() && r.is_marker() && r.status == Some(StepStatus::Ok))
            .count(),
        last_ts: last.map(|r| r.started_at.map(|t| t.to_rfc3339()).unwrap_or_default()),
        last_at: last.and_then(|r| r.started_at),
        skill_durations,
        tool_counts,
        agents,
        decision_count: records.iter().filter(|r| r.is_decision()).count(),
        failure_count: failures(records).len(),
    }
}

/// True when `ts` falls on today's local calendar date.
///
/// Freshness is domain logic, not presentation: it decides whether a log can be
/// read as a description of the current session, and every renderer needs the
/// same answer. Lives here so callers do not each pull in a date library.
pub fn is_today(ts: &str) -> bool {
    match DateTime::parse_from_rfc3339(ts) {
        Err(_) => false,
        Ok(parsed) => {
            parsed.with_timezone(&Local).format("%Y-%m-%d").to_string()
                == Local::now().format("%Y-%m-%d").to_string()
        }
    }
}

/// Human-readable age of a timestamp, e.g. `7d old`.
pub fn age(ts: &str) -> String {
    match DateTime::parse_from_rfc3339(ts) {
        Err(_) => "unparseable".to_string(),
        Ok(parsed) => {
            let days = (Local::now() - parsed.with_timezone(&Local)).num_days();
            if days < 1 {
                "< 1d old".to_string()
            } else {
                format!("{days}d old")
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn rec(json: &str) -> Record {
        record_from_value(serde_json::from_str(json).expect("valid json"))
    }

    // --- crux schema -----------------------------------------------------

    fn crux_step_json(phase: &str) -> String {
        format!(
            r#"{{"name":"ci-fix","kind":"plain","status":"ok","confidence":1.0,
                 "started_at":"2026-09-30T09:00:00+00:00","duration_ms":120,
                 "input_hash":0,"attempt":1,"metadata":{{"phase":"{phase}",
                 "session_id":"s1","trace_id":"t1"}}}}"#
        )
    }

    #[test]
    fn crux_step_carries_phase_from_metadata() {
        assert_eq!(rec(&crux_step_json("start")).phase, Phase::Start);
        assert_eq!(rec(&crux_step_json("terminal")).phase, Phase::Terminal);
    }

    #[test]
    fn crux_step_surfaces_session_and_trace_ids() {
        let r = rec(&crux_step_json("terminal"));
        assert_eq!(r.session_id.as_deref(), Some("s1"));
        assert_eq!(r.trace_id.as_deref(), Some("t1"));
        assert_eq!(r.kind, StepKind::Plain);
        assert_eq!(r.status, Some(StepStatus::Ok));
    }

    // --- legacy schema ---------------------------------------------------

    #[test]
    fn legacy_agent_start_is_open_and_carries_no_status() {
        let r = rec(r#"{"event":"agent.start","agent_id":"explore","session_id":"s1"}"#);
        assert!(r.is_agent());
        assert!(r.is_open());
        assert_eq!(r.status, None, "an open step has no outcome yet");
        assert_eq!(r.name, "explore");
    }

    #[test]
    fn legacy_agent_blocked_is_rejected_not_err() {
        let r = rec(r#"{"event":"agent.blocked","agent_id":"a","reason":"nope"}"#);
        assert_eq!(r.status, Some(StepStatus::Rejected));
        assert!(r.is_failure());
        assert_eq!(r.error.as_deref(), Some("nope"));
    }

    #[test]
    fn legacy_skill_error_is_err() {
        let r = rec(r#"{"event":"skill.error","skill":"cron-refresh","duration_ms":9}"#);
        assert_eq!(r.status, Some(StepStatus::Err));
        assert!(r.is_failure());
        assert_eq!(r.duration_ms, Some(9));
    }

    #[test]
    fn legacy_tool_use_failure_maps_to_err() {
        let ok = rec(r#"{"event":"tool.use","tool":"Bash","failed":false}"#);
        let bad = rec(r#"{"event":"tool.use","tool":"Bash","failed":true}"#);
        assert_eq!(ok.status, Some(StepStatus::Ok));
        assert_eq!(bad.status, Some(StepStatus::Err));
        assert!(bad.is_failure());
    }

    #[test]
    fn legacy_session_start_is_a_nameless_marker() {
        let r = rec(r#"{"event":"session.start","session_id":"s1","ts":"2026-09-30T09:00:00Z"}"#);
        assert_eq!(r.name, "", "a marker has no actor to name it after");
        assert!(r.is_open(), "session.start opens a lifecycle");
        assert_eq!(
            r.session_id.as_deref(),
            Some("s1"),
            "the id is still carried"
        );
    }

    #[test]
    fn legacy_session_end_is_a_nameless_marker_that_still_counts_as_an_end() {
        let r = rec(r#"{"event":"session.end","session_id":"s1","ts":"2026-09-30T09:05:00Z"}"#);
        assert_eq!(r.name, "");
        assert!(r.is_marker());
        assert_eq!(
            r.status,
            Some(StepStatus::Ok),
            "stats' session_ends filter requires Ok on a nameless terminal record"
        );
    }

    #[test]
    fn a_nameless_non_marker_legacy_line_still_falls_back_to_session_id() {
        let r = rec(r#"{"event":"hook.observed","session_id":"s1"}"#);
        assert_eq!(
            r.name, "s1",
            "the session_id fallback must survive for everything that is not a marker"
        );
        assert!(!r.is_marker());
    }

    #[test]
    fn stats_counts_a_session_start_and_sees_the_session_as_active() {
        let body = concat!(
            r#"{"event":"session.start","session_id":"s1","ts":"2026-09-30T09:00:00Z"}"#,
            "\n",
            r#"{"event":"skill.error","skill":"ci-fix","session_id":"s1","ts":"2026-09-30T09:00:01Z","duration_ms":9}"#,
        );
        let s = stats(&parse(body));
        assert_eq!(s.session_starts, 1, "the marker must now be counted");
        assert_eq!(s.session_ends, 0);
        assert_eq!(s.distinct_sessions, 1);
        assert_eq!(
            s.active_sessions, 1,
            "s1 recorded a skill.error, so it did work"
        );
    }

    #[test]
    fn stats_excludes_a_marker_only_session_from_active_sessions() {
        let body = concat!(
            r#"{"event":"session.start","session_id":"s1","ts":"2026-09-30T09:00:00Z"}"#,
            "\n",
            r#"{"event":"session.start","session_id":"s2","ts":"2026-09-30T10:00:00Z"}"#,
            "\n",
            r#"{"event":"skill.error","skill":"ci-fix","session_id":"s2","ts":"2026-09-30T10:00:01Z","duration_ms":9}"#,
        );
        let s = stats(&parse(body));
        assert_eq!(
            s.distinct_sessions, 2,
            "both ids appear in the log, so both are distinct sessions"
        );
        assert_eq!(
            s.active_sessions, 1,
            "only s2 recorded anything beyond a marker"
        );
    }

    #[test]
    fn legacy_decision_is_a_branch() {
        let r = rec(r#"{"event":"decision","skill":"ci-fix","kind":"ci_class","value":"flaky"}"#);
        assert!(r.is_decision());
        assert_eq!(r.kind, StepKind::Branch);
    }

    #[test]
    fn legacy_slot_survives_into_metadata() {
        // `slot` is documented on agent.blocked but never emitted on
        // agent.start. Reading it must never be an error, only an absent field.
        let r = rec(r#"{"event":"agent.blocked","agent_id":"a","slot":"2"}"#);
        assert_eq!(r.meta_str("slot"), Some("2"));
        let start = rec(r#"{"event":"agent.start","agent_id":"a"}"#);
        assert_eq!(start.meta_str("slot"), None);
    }

    #[test]
    fn legacy_record_without_session_id_parses() {
        let r = rec(r#"{"event":"hook_observed","ts":"2026-01-01T00:00:00Z"}"#);
        assert!(r.session_id.is_none());
        assert!(r.started_at.is_some());
    }

    // --- parsing ---------------------------------------------------------

    #[test]
    fn parse_skips_blank_torn_and_malformed_lines() {
        let body = concat!(
            r#"{"event":"skill.start","skill":"a","session_id":"s1"}"#,
            "\n",
            "\n",
            r#"{"event":"skill.comp"#,
            "\n",
            r#"{"event":"skill.complete","skill":"a","session_id":"s1"}"#,
            "\n",
        );
        let records = parse(body);
        assert_eq!(records.len(), 2, "a torn line must not cost the rest");
    }

    #[test]
    fn parse_of_empty_body_is_empty() {
        assert!(parse("").is_empty());
    }

    // --- queries ---------------------------------------------------------

    fn agent_fixture() -> Vec<Record> {
        vec![
            rec(r#"{"event":"agent.start","agent_id":"a","session_id":"s1"}"#),
            rec(r#"{"event":"agent.complete","agent_id":"a","session_id":"s1"}"#),
            rec(r#"{"event":"agent.start","agent_id":"b","session_id":"s1"}"#),
            rec(r#"{"event":"agent.blocked","agent_id":"b","session_id":"s1"}"#),
            rec(r#"{"event":"agent.start","agent_id":"c","session_id":"s1"}"#),
        ]
    }

    #[test]
    fn unresolved_agents_excludes_closed_identities() {
        let records = agent_fixture();
        let refs: Vec<&Record> = records.iter().collect();
        assert_eq!(unresolved_agents(&refs), vec!["c".to_string()]);
    }

    #[test]
    fn repeated_dispatch_of_one_id_yields_one_unresolved_entry() {
        // The live trace has six `subagent-explore` starts, all unresolved.
        // Convergence is per identity, not per record.
        let records = [
            rec(r#"{"event":"agent.start","agent_id":"x"}"#),
            rec(r#"{"event":"agent.start","agent_id":"x"}"#),
            rec(r#"{"event":"agent.start","agent_id":"x"}"#),
        ];
        let refs: Vec<&Record> = records.iter().collect();
        assert_eq!(unresolved_agents(&refs), vec!["x".to_string()]);
    }

    #[test]
    fn late_completion_resolves_an_earlier_open_step() {
        // Order in a JSONL log is not guaranteed to be start-then-terminal.
        let records = [
            rec(r#"{"event":"agent.complete","agent_id":"a"}"#),
            rec(r#"{"event":"agent.start","agent_id":"a"}"#),
        ];
        let refs: Vec<&Record> = records.iter().collect();
        assert!(unresolved_agents(&refs).is_empty());
    }

    #[test]
    fn session_summary_counts_each_outcome_class() {
        let records = [
            rec(r#"{"event":"skill.start","skill":"a","session_id":"s1"}"#),
            rec(r#"{"event":"skill.error","skill":"a","session_id":"s1"}"#),
            rec(r#"{"event":"agent.blocked","agent_id":"b","session_id":"s1"}"#),
            rec(r#"{"event":"decision","skill":"a","session_id":"s1"}"#),
        ];
        let refs: Vec<&Record> = records.iter().collect();
        let s = summarise_session("s1", &refs);
        assert_eq!(s.errors, 1);
        assert_eq!(s.blocked, 1);
        assert_eq!(s.decisions, 1);
        assert!(s.unresolved.is_empty());
    }

    #[test]
    fn session_ids_preserve_first_seen_order() {
        let records = vec![
            rec(r#"{"event":"skill.start","skill":"a","session_id":"s2"}"#),
            rec(r#"{"event":"skill.start","skill":"a","session_id":"s1"}"#),
            rec(r#"{"event":"skill.start","skill":"a","session_id":"s2"}"#),
        ];
        assert_eq!(session_ids(&records), vec!["s2", "s1"]);
    }

    #[test]
    fn stats_rolls_up_skill_durations() {
        let records = vec![
            rec(r#"{"event":"skill.complete","skill":"a","duration_ms":100}"#),
            rec(r#"{"event":"skill.complete","skill":"a","duration_ms":300}"#),
        ];
        let s = stats(&records);
        assert_eq!(s.skill_durations.len(), 1);
        let d = &s.skill_durations[0];
        assert_eq!(d.runs, 2);
        assert_eq!(d.avg_ms, 200);
        assert_eq!(d.max_ms, 300);
    }

    #[test]
    fn stats_ignores_durations_from_open_records() {
        // A start line can carry a duration field without having finished.
        let records = vec![rec(
            r#"{"event":"skill.start","skill":"a","duration_ms":999}"#,
        )];
        assert!(stats(&records).skill_durations.is_empty());
    }

    #[test]
    fn stats_classifies_agent_convergence() {
        let s = stats(&agent_fixture());
        let by_name = |n: &str| s.agents.iter().find(|(x, _)| x == n).map(|(_, v)| *v);
        assert_eq!(by_name("a"), Some(AgentStatus::Complete));
        assert_eq!(by_name("b"), Some(AgentStatus::Blocked));
        assert_eq!(by_name("c"), Some(AgentStatus::Running));
    }

    #[test]
    fn stats_counts_failures_across_both_statuses() {
        let s = stats(&agent_fixture());
        assert_eq!(s.failure_count, 1, "only the blocked agent is a failure");
    }

    #[test]
    fn tail_returns_most_recent_in_file_order() {
        let records = vec![
            rec(r#"{"event":"skill.start","skill":"a"}"#),
            rec(r#"{"event":"skill.start","skill":"b"}"#),
            rec(r#"{"event":"skill.start","skill":"c"}"#),
        ];
        let t = tail(&records, 2);
        assert_eq!(t.len(), 2);
        assert_eq!(t[0].name, "b");
        assert_eq!(t[1].name, "c");
    }

    #[test]
    fn tail_larger_than_input_returns_everything() {
        let records = vec![rec(r#"{"event":"skill.start","skill":"a"}"#)];
        assert_eq!(tail(&records, 99).len(), 1);
    }

    #[test]
    fn age_of_unparseable_timestamp_is_labelled() {
        assert_eq!(age("not a timestamp"), "unparseable");
    }
}