lernie 0.0.3

A git-backed agent harness
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

//! Silent-death sweep tests (ARCH §8): the never-deposited-child deposit,
//! idempotence, the returned/driven/root exclusions, and died-mid-work.

use super::*;

// ---- the never-deposited child gets one died deposit ----

#[test]
fn sweep_deposits_died_for_a_child_that_never_returned() {
    let ws = TempDir::new().unwrap();
    let git = StubGit::with_branches(&["main", PARENT, CHILD]).tip(CHILD, "cafef00d");
    let launcher = StubLauncher::default();
    let report = scan(ws.path(), &git, &FixedClock, &launcher).unwrap();

    assert_eq!(report.swept, vec![CHILD.to_string()]);
    assert_eq!(report.silent_deaths, vec![CHILD.to_string()]);
    // The deposit is a message *from the child* in the parent's inbox.
    let deposited = inbox_dir(ws.path(), PARENT).join(format!("{CHILD}-001.md"));
    let body = std::fs::read_to_string(&deposited).unwrap();
    assert!(
        body.contains(&format!("from: {CHILD}")),
        "sender is the child"
    );
    assert!(body.contains("epitaph: died"));
    assert!(body.contains("terminal_ref: cafef00d"));
    // The flush that follows launches a driver for the freshly-filled
    // parent inbox — never for the child (nothing pending there).
    assert_eq!(report.flushed, vec![PARENT.to_string()]);
    assert_eq!(launcher.invocations(), vec![PARENT.to_string()]);
}

#[test]
fn sweep_is_idempotent_across_a_double_scan() {
    let ws = TempDir::new().unwrap();
    let git = StubGit::with_branches(&["main", PARENT, CHILD]);
    let launcher = StubLauncher::default();

    let first = scan(ws.path(), &git, &FixedClock, &launcher).unwrap();
    assert_eq!(first.swept, vec![CHILD.to_string()]);

    // Second scan: the prior sweep's own deposit is a message from the
    // child in the parent's inbox, so the never-deposited derivation is
    // now false — no re-deposit, and exactly one died file remains.
    let second = scan(ws.path(), &git, &FixedClock, &launcher).unwrap();
    assert!(second.swept.is_empty(), "no re-deposit on re-scan");
    assert!(second.silent_deaths.is_empty());
    let count = std::fs::read_dir(inbox_dir(ws.path(), PARENT))
        .unwrap()
        .flatten()
        .filter(|e| e.file_name().to_string_lossy().starts_with(CHILD))
        .count();
    assert_eq!(count, 1, "exactly one died deposit");
}

// ---- exclusions: already-returned, driven, root ----

#[test]
fn child_with_a_delivered_transcript_message_is_not_swept() {
    let ws = TempDir::new().unwrap();
    // The parent branch already carries a delivered return from the child.
    let git = StubGit::with_branches(&["main", PARENT, CHILD])
        .ls_tree(PARENT, &format!("messages/003-{CHILD}.md\n"));
    let report = scan(ws.path(), &git, &FixedClock, &StubLauncher::default()).unwrap();
    assert!(
        report.swept.is_empty(),
        "delivered return counts as returned"
    );
    assert!(report.silent_deaths.is_empty());
}

#[test]
fn child_with_an_undelivered_inbox_message_is_not_swept() {
    let ws = TempDir::new().unwrap();
    // A result already sits undelivered in the parent's inbox.
    deposit_msg(ws.path(), PARENT, &format!("{CHILD}-001.md"));
    let git = StubGit::with_branches(&["main", PARENT, CHILD]);
    let report = scan(ws.path(), &git, &FixedClock, &StubLauncher::default()).unwrap();
    assert!(report.swept.is_empty());
    assert!(report.silent_deaths.is_empty());
}

#[test]
fn a_driven_child_is_never_swept() {
    let ws = TempDir::new().unwrap();
    // Simulate a live executor by holding the child's lock across the scan.
    let _held = try_acquire(&inbox_dir(ws.path(), CHILD))
        .unwrap()
        .expect("free");
    let git = StubGit::with_branches(&["main", PARENT, CHILD]);
    let report = scan(ws.path(), &git, &FixedClock, &StubLauncher::default()).unwrap();
    assert!(report.swept.is_empty(), "held lock is not a silent death");
    assert!(report.silent_deaths.is_empty());
}

#[test]
fn a_root_is_counted_but_never_deposited() {
    let ws = TempDir::new().unwrap();
    // A root that died mid-work: latest response.json has no terminal end.
    write_response(ws.path(), PARENT, "001", KILLED);
    let git = StubGit::with_branches(&["main", PARENT]);
    let report = scan(ws.path(), &git, &FixedClock, &StubLauncher::default()).unwrap();
    assert!(report.swept.is_empty(), "a root has no parent inbox");
    assert_eq!(
        report.silent_deaths,
        vec![PARENT.to_string()],
        "died-mid-work root is a silent death, surfaced by name"
    );
}

#[test]
fn a_root_with_a_failed_model_call_is_a_named_silent_death() {
    // bl-ee80: a non-retryable (or retries-exhausted) model-call error
    // ends its segment cleanly — an `Error` then the terminal `end` — so
    // the branch looks idle to a no-terminal-`end` test while being
    // permanently unable to advance (§2.10: the model call never settled
    // complete, no transcript entry committed). The sweep classifies it
    // dead from the same framing tail and, the root having no parent
    // inbox to deposit into, its *name* in the report is the surfacing.
    let ws = TempDir::new().unwrap();
    write_response(ws.path(), PARENT, "001", FAILED);
    let git = StubGit::with_branches(&["main", PARENT]);
    let report = scan(ws.path(), &git, &FixedClock, &StubLauncher::default()).unwrap();
    assert!(report.swept.is_empty(), "a root gets no deposit");
    assert_eq!(report.silent_deaths, vec![PARENT.to_string()]);
    assert!(
        report
            .to_string()
            .contains(&format!("silent deaths: 1 ({PARENT})")),
        "{report}"
    );
}

#[test]
fn a_branch_whose_derived_parent_has_no_ref_is_treated_as_a_root() {
    // bl-025b. `parent_of` is string arithmetic over the hyphenated
    // descent; whether that address names an agent is a query against
    // the `agents/*` registry. An odd-token branch (or one whose parent
    // ref was deleted) derives an address that holds no ref. Before the
    // intersection the sweep asked git for `agents/<that>` anyway and
    // the 128 aborted the WHOLE pass — sweep and flush both — so mail
    // pending elsewhere went unflushed. It is nobody's child: no parent
    // inbox, so nothing to deposit and nothing to ask.
    let ws = TempDir::new().unwrap();
    let orphan = format!("{PARENT}-c0ffee");
    // The one-token suffix makes three tokens; `parent_of` strips two.
    assert_eq!(parent_of(&orphan).as_deref(), Some("20260101"));
    deposit_msg(ws.path(), PARENT, "user-001.md");
    let git = StubGit::with_branches(&[PARENT, orphan.as_str()]);
    let launcher = StubLauncher::default();
    let report = scan(ws.path(), &git, &FixedClock, &launcher).unwrap();

    assert!(report.swept.is_empty(), "no parent inbox to deposit into");
    assert!(
        report.silent_deaths.is_empty(),
        "alive-and-quiet, like a root"
    );
    assert!(
        !git.asked_ls_tree_for("20260101"),
        "no git question about a ref the registry does not hold"
    );
    // The pass survives to its second half: the flush still runs.
    assert_eq!(report.flushed, vec![PARENT.to_string()]);
    assert_eq!(launcher.invocations(), vec![PARENT.to_string()]);
}

#[test]
fn an_absent_parent_inbox_reads_as_no_undelivered_return() {
    // `returned`'s inbox half is total over a missing directory — the
    // general path with empty inputs, not a bootstrap case. Asserted at
    // the predicate's own level because the sweep cannot reach it: the
    // registry intersection (bl-025b) means the parent is always an
    // enumerated agent, a refname sorts before every id extending it, and
    // that earlier iteration's lock probe `create_dir_all`s the inbox. An
    // *unreadable* one still lands here in production, so the arm stays.
    let ws = TempDir::new().unwrap();
    assert!(!inbox_dir(ws.path(), PARENT).exists());
    assert!(!returned(ws.path(), &StubGit::default(), PARENT, CHILD).unwrap());
}

// ---- died_mid_work derivation over steps/ ----

#[test]
fn died_mid_work_reads_the_latest_step_response() {
    let ws = TempDir::new().unwrap();
    // Step 1 completed cleanly; step 2 was killed — the latest governs.
    write_response(ws.path(), PARENT, "001", COMPLETE);
    write_response(ws.path(), PARENT, "002", KILLED);
    assert!(died_mid_work(ws.path(), PARENT));
}

#[test]
fn a_failed_latest_response_is_a_death() {
    // §2.10: an `Error`-terminated final segment (with its clean `end`)
    // is equally dead — the model call never settled complete.
    let ws = TempDir::new().unwrap();
    write_response(ws.path(), PARENT, "001", FAILED);
    assert!(died_mid_work(ws.path(), PARENT));
}

#[test]
fn a_complete_latest_response_is_not_a_death() {
    let ws = TempDir::new().unwrap();
    write_response(ws.path(), PARENT, "001", KILLED);
    write_response(ws.path(), PARENT, "002", COMPLETE);
    assert!(!died_mid_work(ws.path(), PARENT));
}

#[test]
fn no_steps_tree_is_not_a_death() {
    let ws = TempDir::new().unwrap();
    assert!(
        !died_mid_work(ws.path(), CHILD),
        "shipped child shape: no steps/"
    );
    // A steps/ dir with no numeric step is likewise silent.
    std::fs::create_dir_all(ws.path().join(STEPS_DIR).join(CHILD).join("junk")).unwrap();
    assert!(!died_mid_work(ws.path(), CHILD));
    // A numeric latest step whose response.json is absent (a death before
    // the model call even opened one) reads silent — no framing to judge.
    std::fs::create_dir_all(ws.path().join(STEPS_DIR).join(CHILD).join("001")).unwrap();
    assert!(!died_mid_work(ws.path(), CHILD));
}