lernie 0.0.4

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
223
224
225
226

//! Deterministic coverage of the §2.11 release rule (bl-9c8f). The
//! lost-wakeup window is [holder's last inbox read, holder's release];
//! the seen-set *names* that read, so a test holds the window open by
//! construction — deposit after the set was taken, then release — no
//! sleeps, no widened drains, no e2e flake-hunting.

use super::super::drain::SeenDeposit;
use super::{release_then_reprobe, reprobe_after_release};
use crate::prompt::SystemClock;
use crate::prompt::inbox::{
    Epitaph, Launcher, ProbeOutcome, deposit, deposit_result, inbox_dir, probe_and_launch,
    try_acquire,
};
use std::cell::RefCell;
use std::io;
use std::path::Path;
use tempfile::TempDir;

/// The [`SeenDeposit`] identity of a real deposited file: its name plus
/// its on-disk mtime — what a drain that enumerated and held it records.
fn seen_of(path: &Path) -> SeenDeposit {
    SeenDeposit::new(
        path.file_name().unwrap().to_string_lossy().into_owned(),
        std::fs::metadata(path).unwrap().modified().unwrap(),
    )
}

/// A root-shaped agent id (two hyphen-free tokens, §2.3).
const AGENT: &str = "20260101-a1";

/// A no-op [`crate::template::GitRunner`] for deposits into a bare
/// `TempDir` workspace: the returned-mark `update-ref` has no repo.git
/// to land in here, and these tests read only the inbox files.
struct OkGit;
impl crate::template::GitRunner for OkGit {
    fn run(&self, _dest: &Path, _args: &[&str]) -> io::Result<()> {
        Ok(())
    }
    fn run_capture(&self, _dest: &Path, _args: &[&str]) -> io::Result<String> {
        Ok(String::new())
    }
}

/// Recording [`Launcher`]: what the release rule fired, and at whom.
#[derive(Default)]
struct RecLauncher {
    launches: RefCell<Vec<String>>,
}
impl Launcher for RecLauncher {
    fn launch(&self, _ws: &Path, agent: &str) -> io::Result<()> {
        self.launches.borrow_mut().push(agent.to_string());
        Ok(())
    }
}

/// A launcher that cannot spawn — the fire-and-forget swallow arm.
struct FailLauncher;
impl Launcher for FailLauncher {
    fn launch(&self, _ws: &Path, _agent: &str) -> io::Result<()> {
        Err(io::Error::other("spawn refused"))
    }
}

#[test]
fn a_deposit_racing_the_holders_last_read_is_launched_at_release() {
    // The proven strand (bl-9c8f), replayed deterministically: holder H
    // acquires; H's last inbox read sees nothing (seen = []); writer W
    // deposits; W's probe reads Busy and defers to H — the deferral that
    // used to strand the deposit forever; H releases through the rule
    // and completes W's launch.
    let ws = TempDir::new().unwrap();
    let holder = try_acquire(&inbox_dir(ws.path(), AGENT))
        .unwrap()
        .expect("free");
    let seen: Vec<SeenDeposit> = Vec::new();
    deposit(ws.path(), AGENT, "user", "racing mail", &SystemClock).unwrap();
    let rec = RecLauncher::default();
    assert_eq!(
        probe_and_launch(ws.path(), AGENT, &rec).unwrap(),
        ProbeOutcome::Busy,
        "the writer's probe must defer to the live holder"
    );
    assert!(rec.launches.borrow().is_empty());
    release_then_reprobe(holder, ws.path(), AGENT, &seen, &rec);
    // The launch fired — which also proves the lease really released,
    // since the rule's own probe would read Busy against a held lock.
    assert_eq!(*rec.launches.borrow(), vec![AGENT.to_string()]);
    // Launching is not delivering: the mail still awaits its driver.
    assert_eq!(
        std::fs::read_dir(inbox_dir(ws.path(), AGENT))
            .unwrap()
            .count(),
        1
    );
}

#[test]
fn mail_the_holders_last_read_saw_never_relaunches() {
    // Termination: a deposit the holder enumerated and deliberately left
    // (the §6 gate-hold shape) is in the seen-set, so the release fires
    // nothing — hold → no-op driver → hold cannot relaunch-loop.
    let ws = TempDir::new().unwrap();
    let holder = try_acquire(&inbox_dir(ws.path(), AGENT))
        .unwrap()
        .expect("free");
    let held = deposit(ws.path(), AGENT, "user", "held mail", &SystemClock).unwrap();
    let seen = vec![seen_of(&held)];
    let rec = RecLauncher::default();
    release_then_reprobe(holder, ws.path(), AGENT, &seen, &rec);
    assert!(rec.launches.borrow().is_empty());
}

#[test]
fn a_reused_name_is_a_new_deposit_and_fires_the_release() {
    // Deposit names are max-present-plus-one over the current listing
    // (§2.11 *Deposit*), so mail the holder delivered or interpreted
    // frees its name for a racing writer to mint again. Identity is the
    // (name, mtime) file pair, never the name: a seen name with a fresh
    // mtime is a new deposit, owed its launch like any other.
    let ws = TempDir::new().unwrap();
    let holder = try_acquire(&inbox_dir(ws.path(), AGENT))
        .unwrap()
        .expect("free");
    let racing = deposit(ws.path(), AGENT, "user", "racing mail", &SystemClock).unwrap();
    // A seen-set naming the same file name at a different instant — the
    // consumed predecessor whose name the racing deposit reused.
    let seen = vec![SeenDeposit::new(
        racing.file_name().unwrap().to_string_lossy().into_owned(),
        std::time::SystemTime::UNIX_EPOCH,
    )];
    let rec = RecLauncher::default();
    release_then_reprobe(holder, ws.path(), AGENT, &seen, &rec);
    assert_eq!(*rec.launches.borrow(), vec![AGENT.to_string()]);
}

#[test]
fn a_rival_holding_the_freed_lease_defers_the_reprobe() {
    // No double-drive: the re-read runs strictly after the release, so a
    // rival that won the freed lease first turns the releaser's probe
    // into the ordinary Busy deferral (Writer/driver totality) — and the
    // rival's own release re-reads when it comes.
    let ws = TempDir::new().unwrap();
    let _rival = try_acquire(&inbox_dir(ws.path(), AGENT))
        .unwrap()
        .expect("free");
    deposit(ws.path(), AGENT, "user", "new mail", &SystemClock).unwrap();
    let rec = RecLauncher::default();
    reprobe_after_release(ws.path(), AGENT, &[], &rec);
    assert!(rec.launches.borrow().is_empty());
}

#[test]
fn a_racing_result_is_completed_per_its_own_epitaph_warrant() {
    // The dual completes the launch the racing writer was *owed*, no
    // more — pin 2's one epitaph decision, replayed at the raced
    // boundary so a deposit's fate never turns on the release
    // millisecond: a final-response return would have probe-and-launched
    // had it landed after the release (the child's own revive_parent),
    // so the releaser completes it; a stopped or budget-exhausted return
    // never launches, so the release parks it exactly as the unraced
    // path does (§2.11 "stays undelivered ... the next explicit touch").
    let child = "20260101-a1-20260102-b2";
    for (epitaph, launches) in [
        (Epitaph::FinalResponse, true),
        (Epitaph::Died, true),
        (Epitaph::Stopped, false),
        (Epitaph::BudgetExhausted, false),
    ] {
        let ws = TempDir::new().unwrap();
        deposit_result(
            ws.path(),
            AGENT,
            child,
            epitaph,
            "abc123",
            None,
            &SystemClock,
            &OkGit,
        )
        .unwrap();
        let rec = RecLauncher::default();
        reprobe_after_release(ws.path(), AGENT, &[], &rec);
        assert_eq!(
            !rec.launches.borrow().is_empty(),
            launches,
            "epitaph {:?} must {}launch",
            epitaph,
            if launches { "" } else { "not " }
        );
    }
}

#[test]
fn an_illegible_deposit_body_launches_rather_than_classifies() {
    // No launcher decides warrant (§2.11): a deposit whose body cannot
    // be read gets the launch, and the launched driver sorts it out
    // under the lock. A directory wearing a deposit's name is the
    // deterministic unreadable body.
    let ws = TempDir::new().unwrap();
    std::fs::create_dir_all(inbox_dir(ws.path(), AGENT).join("user-001.md")).unwrap();
    let rec = RecLauncher::default();
    reprobe_after_release(ws.path(), AGENT, &[], &rec);
    assert_eq!(*rec.launches.borrow(), vec![AGENT.to_string()]);
}

#[test]
fn an_unreadable_inbox_reread_is_swallowed() {
    // Accepted crash class (§2.11): the lease is already gone, so a
    // failed re-read may only log — the stranding is late, never lost,
    // and the next touch (`lernie scan`, a reprompt) heals it.
    let ws = TempDir::new().unwrap();
    std::fs::create_dir_all(ws.path().join("inbox")).unwrap();
    std::fs::write(inbox_dir(ws.path(), AGENT), b"not a dir").unwrap();
    let rec = RecLauncher::default();
    reprobe_after_release(ws.path(), AGENT, &[], &rec);
    assert!(rec.launches.borrow().is_empty());
}

#[test]
fn a_failed_post_release_launch_is_swallowed() {
    // Fire-and-forget (§2.11): unseen mail over a free lease warrants a
    // launch, and a spawn refusal is logged and swallowed, never raised.
    let ws = TempDir::new().unwrap();
    deposit(ws.path(), AGENT, "user", "mail", &SystemClock).unwrap();
    reprobe_after_release(ws.path(), AGENT, &[], &FailLauncher);
}