Skip to main content

hermit/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9// Treat all Clippy warnings as errors.
10#![doc = include_str!("../README.md")]
11#![deny(clippy::all)]
12#![allow(clippy::uninlined_format_args)]
13
14// This host library retains LiteInst code without becoming an in-guest Tool
15// image. Declare its historical backing explicitly and keep the host allocator;
16// LiteInst's allocation preflight still refuses non-Tool allocations.
17#[cfg(feature = "liteinst")]
18reverie_liteinst::declare_legacy_tool_backing!();
19
20mod backend_stats;
21pub mod build_info;
22pub mod canonical_verdict;
23mod chroot;
24use hermit_record_format::consts;
25pub mod logdiff_report;
26// TODO-HUMAN-REVIEW(PR-594): Review the public e9patch preprocessing API.
27pub mod cpu_profile_admission;
28pub mod e9patch;
29mod error;
30use hermit_record_format::event;
31use hermit_record_format::event_stream;
32pub mod happens_before;
33pub mod host_input_change;
34mod id;
35#[cfg(feature = "liteinst")]
36pub mod in_guest_exits;
37pub mod instruction_map;
38#[cfg(feature = "liteinst")]
39use hermit_record_format::interp;
40pub mod liteinst_bootstrap;
41mod liteinst_constructor;
42pub mod liteinst_record;
43mod metadata;
44pub mod xstate_probe;
45/// Diagnostic writes that never wait for a reader; they live in detcore, whose
46/// own stderr writer reads the same flag.
47pub use detcore::nonwaiting_write;
48pub mod physical_exit_watch;
49pub mod preemption_admission;
50pub mod proc_mount;
51mod ptrace_completion;
52
53pub use canonical_verdict::Verdict;
54
55/// Whether record/replay verification hashes syscall output buffers, and
56/// therefore whether its log comparison can see buffer CONTENT at all.
57///
58/// ONE CONSTANT BECAUSE TWO INDEPENDENT SWITCHES HAD TO AGREE AND SILENTLY DID
59/// NOT MATTER. Record/replay carried this decision twice: `metadata.rs`'s
60/// `record_or_replay_config` decided whether the recorder EMITS the hash, and
61/// `record_start.rs`'s `ComparisonOptions` decided whether the comparator READS
62/// it. Both were hard-coded `false`, neither was reachable from the command
63/// line, and nothing related them. Setting either alone achieves nothing: hash
64/// without compare is dead weight, compare without hash finds nothing. Naming
65/// the decision once makes the pair impossible to desynchronize, and makes
66/// changing it a one-line edit in a place a reader can find.
67pub const RECORD_REPLAY_HASHES_IO_BUFFERS: bool = true;
68
69/// Whether record/replay virtualizes time. FALSE, DELIBERATELY, AND THAT IS WHY
70/// A GREEN RECORD/REPLAY VERDICT IS NOT A DETERMINISM RESULT.
71///
72/// Named for the same reason as [`RECORD_REPLAY_HASHES_IO_BUFFERS`] directly
73/// above: the decision was about to be carried twice. `metadata.rs`'s
74/// `record_or_replay_config` sets the config the recorder and replayer run
75/// under, and `record_start.rs`'s `ComparisonOptions` now discloses that setting
76/// in the verdict. If those two disagreed, the report would describe a time
77/// policy the run did not use — which is precisely the class of defect the
78/// disclosure exists to close, reintroduced one layer up.
79///
80/// `hermit run --verify` reads its value from the live `det_config` instead,
81/// because `--no-virtualize-time` makes it a genuine runtime choice there. Only
82/// the record/replay path is a fixed decision, so only it gets a constant.
83pub const RECORD_REPLAY_VIRTUALIZES_TIME: bool = false;
84
85/// Exit status for a completed comparison that found a divergence.
86///
87/// This is the conventional `diff` result: zero means equal and one means
88/// different. The verification JSON distinguishes it from a guest that exits
89/// one of its own accord.
90pub const HERMIT_VERIFICATION_DIVERGENCE_EXIT: i32 = 1;
91
92/// Exit status for a failure of HERMIT ITSELF, as distinct from the guest's.
93///
94/// ⚠️ EVERY CLI ERROR USED TO BE `Exited(1)`, WHICH IS THE SINGLE MOST COMMON
95/// GUEST FAILURE CODE. A tracer panic and a guest that exited 1 of its own
96/// accord were therefore INDISTINGUISHABLE from `$?` alone — and every harness,
97/// gate and script on this project decides pass/fail from exactly that value.
98/// The information was not missing, only discarded: reverie's container reports
99/// the child's real status as a typed `ExitStatus`, and hermit collapsed it to
100/// prose and then to `1`.
101///
102/// WHY THIS DOES NOT BREAK THE "hermit's exit IS the guest's exit" CONTRACT.
103/// That contract describes the case where the guest RAN AND EXITED, and it is
104/// untouched: a guest status still flows through `raise_or_exit` unchanged, and
105/// only the `Err` arm — where there is NO guest exit code, because hermit failed
106/// before or instead of producing one — uses this value. The contract did not
107/// cover that case; it does now.
108///
109/// WHY 125. It is the established convention for "the wrapper tool itself
110/// failed" — GNU `env`, `chroot` and `timeout` all reserve 125 for exactly this,
111/// leaving 126/127 for exec-level problems. It is not a value hermit emits
112/// anywhere else.
113///
114/// ⚠️ THIS REDUCES A COLLISION, IT DOES NOT REMOVE ONE. A guest is free to exit
115/// 125 deliberately, and every value in 0..=255 is a legal guest status, so no
116/// code can be reserved outright. What it removes is the GUARANTEED collision
117/// with the most common failure code. For an unambiguous signal, read the
118/// `HERMIT_TASK_PANIC` marker on stderr or the verification JSON; this makes the
119/// cheap check — `$?` — stop actively lying.
120///
121/// ⚠️ IT LIVES IN THE LIBRARY, NOT IN `main.rs`, AND THAT PLACEMENT IS THE FIX
122/// FOR HOW IT WENT STALE. It was a private `const` inside the binary, so
123/// `tests/cli.rs` — the only thing that asserts on it — could not name it and
124/// wrote the number out by hand instead. When hermit#2558 moved the value from
125/// `1` to `125`, the definition moved and the sixteen copies did not: eight cli
126/// tests went red on main and stayed red, each failing an assertion about the
127/// exit code rather than about the behaviour it exists to check. Same shape as
128/// [`RECORD_REPLAY_HASHES_IO_BUFFERS`] above — a decision carried in two places
129/// that had to agree and had no way to. Exported here, the tests move with it.
130///
131/// ⚠️ DO NOT FLIP EVERY `Some(1)` YOU FIND. `tests/stress_suite.rs`
132/// asserts `Some(1)` as THE GUEST'S OWN SIGNAL, not as a stale copy of this
133/// constant: there `Some(1) => GuestOutcome::Exposed`, and
134/// `status.code() == Some(1)` IS the `exposes_bug` predicate. It is
135/// pattern-identical to the tests that DID go stale, and it is the OPPOSITE
136/// case -- the assertion is CORRECT and must not move with this constant.
137///
138/// ⚠️ ITS FAILURE MODE IS SILENT SUCCESS. Changing it to 125 would not
139/// turn the stress suite red; it would make `exposes_bug` NEVER FIRE, so the
140/// suite would report no bug exposed forever and pass while blind. A red is
141/// recoverable; a green that cannot fail is not.
142///
143/// REVIEWER RULE: a change to `tests/stress_suite.rs` inside an exit-code head
144/// SHOULD BE REFUSED ON SIGHT AND QUESTIONED.
145pub const HERMIT_INTERNAL_FAILURE_EXIT: i32 = 125;
146
147/// A deadline hermit itself was asked to enforce expired: **124**.
148///
149/// The status the container init exits with when a hermit-owned bound ends the
150/// run -- `run --timeout`'s SIGALRM fallback here, and `record --record-timeout`'s
151/// handler in `record_start.rs`, which has always used this value. 124 is the
152/// established code for "a deadline fired" across GNU `timeout`, `safehermit`'s
153/// wall bound and both hermit spellings, so this names an existing convention
154/// rather than claiming a new number.
155///
156/// ⚠️ IT MUST BE READ AT THE CONTAINER BOUNDARY OR IT IS SILENTLY REWRITTEN TO
157/// 125. Found only by forcing the fallback to fire, 2026-08-26: the init exited
158/// 124, `classify_container_result` had no arm for it, and it fell through to
159/// `ContainerChildExit` -- so the run reported `exit 125` and
160/// `class=container-child-exit`, "the child died with a status it did not
161/// pick", for a deadline hermit chose to enforce. Identical in shape to the
162/// refusal that arrives as 122 and needs its own arm for the same reason.
163pub const HERMIT_DEADLINE_EXIT: i32 = 124;
164
165/// Hermit's own log output exceeded `--max-log-bytes`: **123**.
166///
167/// The status hermit exits with when the byte budget on its tracing output
168/// (stderr, or `--log-file`) is exhausted and it deliberately tears the run
169/// down. 123 was already reserved below for "a LOG BYTE CAP fired" on behalf of
170/// dev-hermit's `bin/safehermit`; this is the same event enforced one layer
171/// lower, exactly as 124 is shared by hermit's `--timeout` and safehermit's wall
172/// deadline. It is not 125 because the cap working is not hermit breaking, and
173/// not 122 because no fail-closed determinism policy was involved: the remedy
174/// is "lower the log level or raise the cap", not "change the program".
175///
176/// Like 124, it must be read at the container boundary
177/// (`classify_container_result`) or it is rewritten to 125.
178pub const HERMIT_LOG_CAP_EXIT: i32 = 123;
179
180/// The guest program could not be found at all: **127**.
181///
182/// Exported for the same reason as [`HERMIT_INTERNAL_FAILURE_EXIT`] and with the
183/// same history one step behind it. `GuestProgramFault::exit_code` wrote `127`
184/// and `126` as bare literals, and `tests/cli.rs` had no way to name either, so
185/// a test meaning "not found" and a test meaning "hermit refused" were asserted
186/// with the same helper and the same number until the values diverged.
187///
188/// ⚠️ THIS IS NOT A SUBDIVISION OF HERMIT'S OWN FAILURE, AND THAT IS THE WHOLE
189/// DISTINCTION. 125 says *hermit* broke; 127 and 126 say *the guest program* was
190/// unusable and hermit correctly declined to start it. A caller that cannot tell
191/// those apart cannot tell "fix my tooling" from "fix my command line".
192pub const GUEST_PROGRAM_NOT_FOUND_EXIT: i32 = 127;
193
194/// The guest program exists but cannot be executed as given: **126**.
195///
196/// See [`GUEST_PROGRAM_NOT_FOUND_EXIT`]. 127/126 are the GNU `env`/`chroot`/
197/// `timeout` convention that 125 itself came from, so the three sit in one
198/// scheme rather than being three unrelated numbers.
199pub const GUEST_PROGRAM_NOT_EXECUTABLE_EXIT: i32 = 126;
200
201// ⚠️ THE VALUES THEMSELVES ARE PINNED, NOT ONLY THEIR NAMES.
202//
203// Naming a constant makes every consumer agree with the definition; it does not
204// make the definition right. Once `tests/cli.rs` asserts `Some(THE_CONSTANT)`
205// everywhere, the whole suite is self-consistent and completely unanchored -- a
206// one-character edit here would move all sixteen assertions with it and nothing
207// would fail. That is the exact shape of the defect this scheme exists to close,
208// displaced one level up, and it is why these are compile-time assertions rather
209// than a comment: a deliberate edit "would be noticed" is the argument that
210// already failed once, when hermit#2558 moved 1 -> 125 and sixteen copies went
211// stale.
212//
213// WHY EACH VALUE AND NOT ANOTHER. GNU `env`, `chroot` and `timeout` reserve 125
214// for "the wrapper itself failed", 127 for "command not found" and 126 for
215// "found but not executable". Borrowing the whole scheme rather than one number
216// is what keeps the three answers distinguishable from each other.
217//
218// ⚠️ THE EXIT-CODE ALLOCATION FOR THE `hermit` BINARY. ONE TABLE, HERE.
219//
220// Five separate exit-code defects were found in one evening and every one of
221// them came from a value being chosen, copied or rewritten somewhere that could
222// not see the others. This is the single place the space is allocated; anything
223// that emits or rewrites a hermit exit status is a consumer OF this table and
224// must not invent its own reading of it.
225//
226//   0          success.
227//   1          HERMIT_VERIFICATION_DIVERGENCE_EXIT, matching `diff`; also a
228//              legal guest status. Read the verification JSON to distinguish.
229//   2 ..= 121  THE GUEST'S OWN STATUS, passed through untouched. (The range
230//              stops at 121 because 122 is reserved below; a guest may still
231//              CHOOSE any value, see the caveat at the end.)
232//   122        HERMIT_POLICY_REFUSAL_EXIT -- hermit REFUSED the run under a
233//              fail-closed policy. Hermit WORKED; the run was stopped on
234//              purpose and the reason was printed. Distinct from 125 because
235//              "hermit refused" and "hermit broke" demand opposite responses:
236//              read the refusal and change your program or flags, versus file a
237//              bug. Defined in `detcore-model` because `detcore` emits it and
238//              this crate recognises it, and that is the only crate both
239//              depend on.
240//   123        HERMIT_LOG_CAP_EXIT -- a LOG BYTE CAP fired. Hermit's own
241//              `--max-log-bytes` budget on its tracing output, and the value
242//              reserved for dev-hermit's `bin/safehermit` log-cap kill (which,
243//              as of 2026-09-26, still exits 125 -- see the 125 note below).
244//              Hermit's spelling prints `HERMIT_LOG_CAP class=log-cap`.
245//   124        DO NOT USE. GNU `timeout`'s deadline, and dev-hermit's
246//              `bin/safehermit` WALL DEADLINE kill. `tests/cli.rs` asserts
247//              `assert_ne!(code, Some(124))` on the awk-mincore probe.
248//   125        HERMIT_INTERNAL_FAILURE_EXIT -- hermit itself failed, no guest
249//              ran. NOT YET THE SOLE MEANING through dev-hermit's
250//              `bin/safehermit`: that wrapper has exited 125 for its
251//              log-byte-cap kill since it was created on 2026-08-20 and still
252//              did on 2026-10-05, so a run through it produces one number for
253//              two faults with opposite remedies (see "125 ⚠️ NOT FREE" below).
254//              An earlier version of this table said safehermit had already
255//              moved off 125; it never did. The intended fix is that SAFEHERMIT
256//              MOVES -- to the 123 reserved for it above -- NOT HERMIT, because
257//              that wrapper is the only layer that knows which happened (it
258//              relays hermit's status otherwise) and because 125/126/127 is one
259//              GNU scheme that cannot be broken up. Tracked as
260//              `hermit_s_125_collides`.
261//   126        GUEST_PROGRAM_NOT_EXECUTABLE_EXIT.
262//   127        GUEST_PROGRAM_NOT_FOUND_EXIT -- the ABSOLUTE-PATH form. The
263//              bare-name-on-guest-PATH form currently exits 125 instead, which
264//              is an inconsistency tracked as `hermit_reports_a_missing`, not a
265//              second meaning for 127.
266//   128 + N    killed by signal N (shell convention). Hermit does not emit these
267//              deliberately; a wrapper reporting a signal death must use them
268//              rather than borrow a code that already means something.
269//
270// ⚠️ NO CODE IS EXCLUSIVELY HERMIT'S. Every value in 0..=255 is a legal guest
271// status, so a guest may return 125 or 127 of its own accord and this table
272// cannot stop it. The table removes GUARANTEED collisions, not possible ones.
273// The only unambiguous discriminator is the `HERMIT_INTERNAL_FAILURE` marker on
274// stderr, present exactly when hermit itself failed. Any consumer deciding on
275// `$?` alone is guessing, and should say so.
276//
277// ⚠️ THE SAME ARGUMENT APPLIES TO 124, AND MORE SHARPLY, BECAUSE FIVE
278// MECHANISMS PRODUCE IT. `hermit run --timeout`, its unwind fallback, `hermit
279// record --record-timeout`, the `timeout(1)` wrapped around a manifest cell, and
280// `safehermit`'s wall deadline all exit 124, and GNU `timeout` uses it for the
281// same event. They demand different responses -- a slow guest, a wedged
282// teardown inside hermit, a cell bound set too low, a run that escaped every
283// inner bound -- so `$?` cannot route the reader to any of them.
284//
285// The discriminator is again the marker on stderr, and it is a CONTRACT rather
286// than a diagnostic nicety: `class=run-timeout` for hermit's own bound (which
287// also states the bound in seconds), `HERMIT_RUN_TIMEOUT_FALLBACK` for the
288// unwind failing to complete, `safehermit: bound.wall=` for the cgroup reap.
289// EXIT 124 WITH NO MARKER AT ALL MEANS NO INNER BOUND FIRED -- something outside
290// hermit killed the run -- which is a configuration error and not a slow guest.
291// The full picture, including which rung bounds which quantity and the
292// strict-inequality invariant between them, is docs/TIMEOUT_LADDER.md.
293//
294// ⚠️ DO NOT CLAMP INTO THIS RANGE. `scripts/hermit-code-coverage.rs` used
295// `clamp(1, 125)` and so rewrote 127 and 126 into 125 -- turning "your program is
296// missing" into "hermit broke" and pointing the reader at the wrong project.
297// Truncating a status does not lose information here, it MANUFACTURES a false
298// attribution, because the ceiling is itself a meaning.
299//
300// ⚠️ WHAT EACH VALUE MUST NOT COLLIDE WITH -- AND 125 ALREADY DOES.
301//
302//   0    success. Never a failure code; see the nonzero pin below.
303//   1    the commonest guest exit status. Sharing it is the collision
304//        hermit#2558 introduced 125 to escape, so 125 must never drift back.
305//   124  GNU `timeout`'s "deadline fired", and dev-hermit's `bin/safehermit`
306//        uses it for its WALL DEADLINE kill. `tests/cli.rs` asserts
307//        `assert_ne!(code, Some(124))` on the awk-mincore probe for that reason.
308//   126  hermit's own GUEST_PROGRAM_NOT_EXECUTABLE_EXIT.
309//   127  hermit's own GUEST_PROGRAM_NOT_FOUND_EXIT -- already in use for the
310//        ABSOLUTE-PATH form of a missing guest program. Note the bare-name form
311//        resolved against the guest PATH exits 125 instead, which is an
312//        inconsistency filed separately, not a licence to reuse 127.
313//
314//   125  ⚠️ NOT FREE. dev-hermit's `bin/safehermit` exits 125 to mean "the LOG
315//        BYTE CAP fired: safehermit killed the run through its cgroup"
316//        (`demos/lib/demo_common.py`'s SAFEHERMIT_EXIT_REASON). Any hermit run
317//        launched through that wrapper -- which is how the demos and the repeat
318//        harness run it -- can therefore produce 125 for two unrelated reasons:
319//        hermit refused, or the wrapper killed it for log volume. They demand
320//        opposite responses (fix the invocation vs raise the cap), and `$?`
321//        cannot tell them apart. This is a LIVE ambiguity, not a hypothetical:
322//        demo 5 has been observed reporting `exited with status 125` when the
323//        cap fired. It is recorded here rather than resolved because changing
324//        either value is a cross-repository decision.
325//
326//        The discriminator meanwhile is the same one that separates hermit's 125
327//        from a guest's own 125: the `HERMIT_INTERNAL_FAILURE` marker on stderr,
328//        present only when hermit itself failed. safehermit writes its verdict
329//        to its `--sh-report` file instead. Read one of those, never the number
330//        alone.
331//
332// ⚠️ 0 IS THE DANGEROUS DRIFT, NOT 126 OR 127. Every one of these is asserted as
333// `assert_eq!(code, Some(CONST))`. At 0 those assertions would stop demanding a
334// FAILURE and start demanding a SUCCESS, and would still pass -- sixteen tests
335// silently inverted. `tests/cli.rs` also asserts `!status.success()` beside the
336// code for that reason; this pin is the second of the two locks.
337const _: () = assert!(
338    HERMIT_VERIFICATION_DIVERGENCE_EXIT == 1,
339    "1 is the established diff-style result for a completed comparison that diverged"
340);
341const _: () = assert!(
342    HERMIT_INTERNAL_FAILURE_EXIT == 125,
343    "125 is the GNU wrapper-failed convention; 1 is the commonest guest status and 0 is success"
344);
345const _: () = assert!(
346    GUEST_PROGRAM_NOT_FOUND_EXIT == 127,
347    "127 is the GNU command-not-found convention and must stay distinct from 125 and 126"
348);
349const _: () = assert!(
350    GUEST_PROGRAM_NOT_EXECUTABLE_EXIT == 126,
351    "126 is the GNU found-but-not-executable convention and must stay distinct from 125 and 127"
352);
353const _: () = assert!(
354    HERMIT_LOG_CAP_EXIT == 123,
355    "123 is Hermit's log-cap code, reserved for bin/safehermit's log-cap kill as well; see the allocation table"
356);
357const _: () = assert!(
358    HERMIT_LOG_CAP_EXIT != 0
359        && HERMIT_VERIFICATION_DIVERGENCE_EXIT != 0
360        && HERMIT_INTERNAL_FAILURE_EXIT != 0
361        && GUEST_PROGRAM_NOT_FOUND_EXIT != 0
362        && GUEST_PROGRAM_NOT_EXECUTABLE_EXIT != 0,
363    "a failure code of 0 would invert every assert_eq!(code, Some(CONST)) into demanding success"
364);
365mod record;
366use hermit_record_format::record_replay_path;
367mod replay;
368#[cfg(feature = "sabre")]
369mod sabre_bootstrap;
370#[cfg(feature = "sabre")]
371mod sabre_ptrace;
372use hermit_record_format::script;
373mod tracer_thread;
374
375#[cfg(feature = "sabre")]
376use std::ffi::OsStr;
377use std::fs;
378use std::io;
379use std::io::Seek;
380use std::io::SeekFrom;
381use std::io::Write;
382#[cfg(feature = "dbt")]
383use std::os::fd::AsFd;
384use std::os::fd::AsRawFd;
385use std::os::fd::FromRawFd;
386#[cfg(any(feature = "sabre", all(test, feature = "liteinst")))]
387use std::os::unix::ffi::OsStrExt;
388#[cfg(feature = "sabre")]
389use std::os::unix::fs::OpenOptionsExt;
390#[cfg(any(feature = "sabre", feature = "liteinst"))]
391use std::os::unix::fs::PermissionsExt;
392use std::path::Path;
393use std::path::PathBuf;
394#[cfg(feature = "sabre")]
395use std::sync::Arc;
396use std::sync::Mutex;
397#[cfg(feature = "sabre")]
398use std::sync::atomic::AtomicBool;
399use std::time::Duration;
400use std::time::Instant;
401
402use anyhow::anyhow;
403use clap::ValueEnum;
404pub use consts::LAST;
405pub use consts::LAST_RUN;
406use consts::MANIFEST_NAME as RUN_MANIFEST_NAME;
407pub use consts::MANIFEST_NAME;
408use consts::METADATA_NAME;
409pub use consts::METADATA_NAME as RECORDING_METADATA_NAME;
410pub use detcore::Config as DetConfig;
411pub use detcore::Detcore;
412pub use detcore::RecordOrReplay;
413#[doc(hidden)]
414#[cfg(feature = "dbt")]
415pub use detcore_dbt::reverie_dbt_runtime_background_init_v2;
416#[doc(hidden)]
417#[cfg(feature = "dbt")]
418pub use detcore_dbt::reverie_dbt_runtime_background_init_v3;
419#[doc(hidden)]
420#[cfg(feature = "dbt")]
421pub use detcore_dbt::reverie_dbt_runtime_name;
422#[doc(hidden)]
423#[cfg(feature = "dbt")]
424pub use detcore_dbt::reverie_dbt_runtime_pre_syscall;
425#[doc(hidden)]
426#[cfg(feature = "dbt")]
427pub use detcore_dbt::reverie_dbt_runtime_ready;
428#[doc(hidden)]
429#[cfg(feature = "dbt")]
430pub use detcore_dbt::reverie_dbt_runtime_thread_exit;
431#[doc(hidden)]
432#[cfg(feature = "dbt")]
433pub use detcore_dbt::reverie_dbt_runtime_thread_init;
434#[doc(hidden)]
435#[cfg(feature = "dbt")]
436pub use detcore_dbt::reverie_dbt_runtime_totals;
437use detcore_model::bundled_signal_facts;
438pub use error::Context;
439pub use error::Error;
440pub use error::FailureKind;
441pub use error::SerializableError;
442use goblin::elf::Elf;
443use goblin::elf::header;
444use goblin::elf::section_header;
445pub use id::Id;
446use metadata::Metadata;
447pub use ptrace_completion::HermitCleanupStage;
448pub use ptrace_completion::HermitCleanupUnconfirmed;
449pub use ptrace_completion::HermitPtraceFailure;
450pub use ptrace_completion::RecoveryRefusal;
451use record::Record;
452use replay::Replay;
453pub use reverie::ExitStatus;
454#[cfg(feature = "sabre")]
455use reverie::GlobalTool;
456pub use reverie::process;
457pub use reverie::process::Command;
458pub use reverie::process::Mount;
459pub use reverie::process::Namespace;
460pub use reverie::process::Output;
461pub use reverie::process::Stdio;
462pub use script::Shebang;
463use serde::Deserialize;
464use serde::Serialize;
465pub use tracer_thread::launch_on_calling_thread;
466
467enum KvmStdinReservation {
468    Open(fs::File),
469    Closed,
470}
471
472static KVM_STDIN_RESERVATION: Mutex<Option<KvmStdinReservation>> = Mutex::new(None);
473
474/// Saves stdin captured before Rust's process startup can reuse a closed fd 0.
475pub fn reserve_kvm_stdin(stdin: Option<fs::File>) -> io::Result<()> {
476    let mut reservation = KVM_STDIN_RESERVATION
477        .lock()
478        .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
479    if reservation.is_some() {
480        return Err(io::Error::new(
481            io::ErrorKind::AlreadyExists,
482            "KVM stdin is already reserved",
483        ));
484    }
485    *reservation = Some(match stdin {
486        Some(file) => KvmStdinReservation::Open(file),
487        None => KvmStdinReservation::Closed,
488    });
489    Ok(())
490}
491
492fn duplicate_current_stdin() -> io::Result<Option<fs::File>> {
493    // SAFETY: F_DUPFD_CLOEXEC duplicates fd 0 without taking ownership of it.
494    let duplicate = unsafe { libc::fcntl(libc::STDIN_FILENO, libc::F_DUPFD_CLOEXEC, 3) };
495    if duplicate >= 0 {
496        // SAFETY: F_DUPFD_CLOEXEC returned a new owned descriptor.
497        return Ok(Some(unsafe { fs::File::from_raw_fd(duplicate) }));
498    }
499    let error = io::Error::last_os_error();
500    if error.raw_os_error() == Some(libc::EBADF) {
501        Ok(None)
502    } else {
503        Err(error)
504    }
505}
506
507fn ensure_kvm_stdin_reserved() -> io::Result<()> {
508    let mut reservation = KVM_STDIN_RESERVATION
509        .lock()
510        .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
511    if reservation.is_none() {
512        *reservation = Some(match duplicate_current_stdin()? {
513            Some(file) => KvmStdinReservation::Open(file),
514            None => KvmStdinReservation::Closed,
515        });
516    }
517    Ok(())
518}
519
520fn reserved_kvm_stdin() -> Result<Option<fs::File>, Error> {
521    ensure_kvm_stdin_reserved()?;
522    let reservation = KVM_STDIN_RESERVATION
523        .lock()
524        .map_err(|_| io::Error::other("KVM stdin reservation lock is poisoned"))?;
525    match reservation.as_ref() {
526        Some(KvmStdinReservation::Open(file)) => Ok(Some(file.try_clone()?)),
527        Some(KvmStdinReservation::Closed) => Ok(None),
528        None => unreachable!("stdin reservation was initialized above"),
529    }
530}
531
532/// A replayable snapshot of the guest's stdin for the output-capturing backends.
533///
534/// `hermit run --verify` executes the guest twice and compares the two runs. The
535/// output-capturing backends historically fed the guest `Stdio::null()`, so any
536/// data piped into hermit (`echo prog | hermit run --strict --verify -- ...`)
537/// was silently dropped. Both runs then saw identical *empty* input and hermit
538/// reported a false "deterministic" success even though the guest never received
539/// its input. `Seekable` holds a read-only, rewindable file so both runs receive
540/// the exact same bytes without being able to modify the caller's input; `None`
541/// means stdin should be `/dev/null` (nothing to replay, or a terminal that
542/// cannot be replayed identically to two runs).
543enum StdinSnapshot {
544    Seekable(fs::File),
545    None,
546}
547
548static OUTPUT_STDIN_SNAPSHOT: Mutex<Option<StdinSnapshot>> = Mutex::new(None);
549
550/// Records a rewindable snapshot of the process stdin so the output-capturing
551/// backends can replay identical input to each run of `hermit run --verify`.
552///
553/// `stdin` is the descriptor captured before Rust startup could reuse a closed
554/// fd 0 (see the binary's `startup_stdin`). A regular-file redirect is reopened
555/// read-only; a pipe/fifo/socket is drained once into a seekable temporary file
556/// and that file is reopened read-only. A terminal (or absent stdin) is treated
557/// as `/dev/null` because a live terminal cannot be replayed identically to two
558/// runs.
559pub fn reserve_output_stdin_snapshot(stdin: Option<fs::File>) -> io::Result<()> {
560    let snapshot = match stdin {
561        None => StdinSnapshot::None,
562        Some(mut file) => {
563            // SAFETY: as_raw_fd borrows the descriptor without taking ownership.
564            let is_tty = unsafe { libc::isatty(file.as_raw_fd()) } == 1;
565            if is_tty {
566                StdinSnapshot::None
567            } else {
568                let replay = if file.stream_position().is_ok() {
569                    // Already seekable (e.g. `< file`): retain it below through
570                    // a read-only descriptor with an independent file offset.
571                    file
572                } else {
573                    // Non-seekable (pipe/fifo/socket): buffer once into a
574                    // seekable temporary file so both --verify runs receive
575                    // identical input.
576                    //
577                    // NAME THE WAIT BEFORE ENTERING IT. This `io::copy` reads to
578                    // EOF, so a stdin that never reaches EOF -- an inherited socket,
579                    // a fifo whose writer stays open -- blocks here FOREVER, before
580                    // the guest has started. Measured: the process wedges with ZERO
581                    // bytes on stdout and stderr and is only cleared by killing it,
582                    // which is indistinguishable from a slow run. That
583                    // indistinguishability is the whole harm; an unbounded wait that
584                    // says what it is waiting for is merely slow, and a reader can
585                    // act on it.
586                    //
587                    // Deliberately UNCONDITIONAL rather than emitted after a delay:
588                    // a message that appears only once N seconds have passed makes
589                    // hermit's own stderr depend on timing, and this project does
590                    // not accept timing-dependent output. Deliberately NOT a
591                    // deadline either -- a 12s slow producer is legitimate and
592                    // delivers, and nothing can separate "slow" from "never" except
593                    // by waiting. This changes no control flow: every input that
594                    // worked before still works, byte for byte, on stdout.
595                    const BUFFERING_NOTE: &str = "hermit: --verify is buffering stdin from a non-seekable stream so both \
596                         runs receive identical input. If this appears to hang, stdin has not \
597                         reached end-of-file; pass `< /dev/null` when the guest needs no input.";
598                    if nonwaiting_write::diagnostics_must_not_wait() {
599                        // Under --max-log-bytes, termination must not depend
600                        // on this write; see `nonwaiting_write`.
601                        nonwaiting_write::write_without_waiting(
602                            libc::STDERR_FILENO,
603                            format!("{BUFFERING_NOTE}\n").as_bytes(),
604                        );
605                    } else {
606                        eprintln!("{BUFFERING_NOTE}");
607                    }
608                    let mut buffered = tempfile::tempfile()?;
609                    io::copy(&mut file, &mut buffered)?;
610                    buffered.seek(SeekFrom::Start(0))?;
611                    buffered
612                };
613
614                // A duplicate would keep the original access mode. Reopen the
615                // reserved descriptor read-only so neither verification run
616                // can modify the caller's stdin or the next run's input.
617                let replay_path = format!("/proc/self/fd/{}", replay.as_raw_fd());
618                StdinSnapshot::Seekable(fs::File::open(replay_path)?)
619            }
620        }
621    };
622    let mut reservation = OUTPUT_STDIN_SNAPSHOT
623        .lock()
624        .map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
625    if reservation.is_some() {
626        return Err(io::Error::new(
627            io::ErrorKind::AlreadyExists,
628            "output stdin snapshot is already reserved",
629        ));
630    }
631    *reservation = Some(snapshot);
632    Ok(())
633}
634
635/// Returns a rewound descriptor for the reserved stdin snapshot, if any.
636///
637/// Each call rewinds the snapshot and hands back a fresh descriptor, so
638/// repeated `--verify` runs read identical input from the start. Returns `None`
639/// when no snapshot was reserved or the reserved stdin is a terminal/absent
640/// (nothing to replay). Runs are sequential (each executes in its own forked
641/// container child), so resetting the shared open file description's offset here
642/// is safe.
643fn output_backend_stdin_reservation() -> Result<(bool, Option<fs::File>), Error> {
644    let mut reservation = OUTPUT_STDIN_SNAPSHOT
645        .lock()
646        .map_err(|_| io::Error::other("output stdin snapshot lock is poisoned"))?;
647    match reservation.as_mut() {
648        Some(StdinSnapshot::Seekable(file)) => {
649            file.seek(SeekFrom::Start(0))?;
650            Ok((true, Some(file.try_clone()?)))
651        }
652        Some(StdinSnapshot::None) => Ok((true, None)),
653        None => Ok((false, None)),
654    }
655}
656
657fn output_backend_stdin_file() -> Result<Option<fs::File>, Error> {
658    Ok(output_backend_stdin_reservation()?.1)
659}
660
661/// Returns the stdin to hand a guest run in an output-capturing backend.
662///
663/// When [`reserve_output_stdin_snapshot`] has stored a replayable snapshot the
664/// file is rewound and a fresh descriptor handed to the guest, so each
665/// `--verify` run reads identical input. Otherwise (no snapshot reserved, or a
666/// terminal/absent stdin) the guest gets `/dev/null`, matching the previous
667/// behavior for callers that do not reserve a snapshot.
668pub fn output_backend_stdin() -> Result<Stdio, Error> {
669    match output_backend_stdin_file()? {
670        Some(file) => Ok(Stdio::from(file)),
671        None => Ok(Stdio::null()),
672    }
673}
674
675/// The result of recording a command.
676#[derive(Debug, Serialize, Deserialize)]
677pub struct Recording {
678    /// The unique ID of the recording.
679    pub id: Id,
680
681    /// The exit code of the command.
682    pub exit_status: ExitStatus,
683}
684
685#[derive(Clone, Copy, Debug, PartialEq, Eq)]
686enum CapabilityProbe {
687    Namespaces,
688    Ptrace,
689    Seccomp,
690}
691
692fn run_capability_probe(probe: CapabilityProbe) -> Result<bool, Error> {
693    // SAFETY: The child calls only async-signal-safe syscalls and exits immediately.
694    let pid = unsafe { libc::fork() };
695    if pid == -1 {
696        return Err(std::io::Error::last_os_error()).context("Failed to fork capability probe");
697    }
698    if pid == 0 {
699        let supported = match probe {
700            CapabilityProbe::Namespaces => unsafe {
701                libc::unshare(libc::CLONE_NEWUSER | libc::CLONE_NEWPID) == 0
702            },
703            CapabilityProbe::Ptrace => {
704                // SAFETY: PTRACE_TRACEME ignores the pid and address arguments.
705                unsafe {
706                    libc::ptrace(
707                        libc::PTRACE_TRACEME,
708                        0,
709                        std::ptr::null_mut::<libc::c_void>(),
710                        std::ptr::null_mut::<libc::c_void>(),
711                    ) != -1
712                }
713            }
714            CapabilityProbe::Seccomp => {
715                let mut filter = libc::sock_filter {
716                    code: 0x06, // BPF_RET | BPF_K
717                    jt: 0,
718                    jf: 0,
719                    k: 0x7fff0000, // SECCOMP_RET_ALLOW
720                };
721                let program = libc::sock_fprog {
722                    len: 1,
723                    filter: &mut filter,
724                };
725                // SAFETY: The filter is an allow-all program with a valid one-element lifetime.
726                unsafe {
727                    libc::prctl(libc::PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0) == 0
728                        && libc::syscall(
729                            libc::SYS_seccomp,
730                            1, // SECCOMP_SET_MODE_FILTER
731                            0,
732                            &program,
733                        ) == 0
734                }
735            }
736        };
737        // SAFETY: Avoid running Rust destructors after fork.
738        unsafe { libc::_exit(i32::from(!supported)) }
739    }
740
741    let mut status = 0;
742    loop {
743        // SAFETY: pid is the child created above and status points to valid storage.
744        let result = unsafe { libc::waitpid(pid, &mut status, 0) };
745        if result == pid {
746            return Ok(libc::WIFEXITED(status) && libc::WEXITSTATUS(status) == 0);
747        }
748        if result == -1 {
749            let error = std::io::Error::last_os_error();
750            if error.kind() == std::io::ErrorKind::Interrupted {
751                continue;
752            }
753            return Err(error).context("Failed to wait for capability probe");
754        }
755    }
756}
757
758/// Whether a run creates Hermit's user and PID namespaces. A `--no-namespace`
759/// run starts the guest as a plain child and never calls `unshare`, so the
760/// namespace probe says nothing about whether it can run
761/// (<https://github.com/rrnewton/hermit/issues/4515>).
762#[derive(Clone, Copy, Debug, PartialEq, Eq)]
763pub enum NamespaceUse {
764    /// The run unshares its user and PID namespaces (the default).
765    Creates,
766    /// The run creates no namespace (`--no-namespace`).
767    None,
768}
769
770fn validate_tracing_environment(namespaces: NamespaceUse) -> Result<(), Error> {
771    check_tracing_environment(namespaces, run_capability_probe)
772}
773
774/// Refuses a ptrace run that `probe` says this environment cannot host: the
775/// namespace probe for a run that creates namespaces, then the ptrace and
776/// seccomp probes for every run, which a `--no-namespace` run needs too.
777fn check_tracing_environment(
778    namespaces: NamespaceUse,
779    mut probe: impl FnMut(CapabilityProbe) -> Result<bool, Error>,
780) -> Result<(), Error> {
781    if namespaces == NamespaceUse::Creates && !probe(CapabilityProbe::Namespaces)? {
782        anyhow::bail!(
783            "Hermit cannot create its required user and PID namespaces: \
784             unshare(CLONE_NEWUSER | CLONE_NEWPID) was denied. Allow unprivileged user namespaces \
785             and the unshare syscall in the host/container policy."
786        );
787    }
788    if !probe(CapabilityProbe::Ptrace)? {
789        anyhow::bail!(
790            "Hermit cannot use ptrace in this environment: a child PTRACE_TRACEME probe was \
791             denied. Allow same-UID parent-child ptrace in the container seccomp and host \
792             Yama/LSM policy; CAP_SYS_PTRACE is normally not required. Use --namespace-only for \
793             a sandbox smoke test without ptrace (it intercepts only kill, through a seccomp \
794             filter)."
795        );
796    }
797    if !probe(CapabilityProbe::Seccomp)? {
798        anyhow::bail!(
799            "Hermit cannot install its tracee seccomp filter: \
800             seccomp(SECCOMP_SET_MODE_FILTER) was denied. Allow seccomp and \
801             prctl(PR_SET_NO_NEW_PRIVS) in the container policy. --namespace-only also \
802             installs a seccomp filter (on kill), so it cannot run here either."
803        );
804    }
805    Ok(())
806}
807
808#[cfg(feature = "dbt")]
809fn is_dynamorio_sdk(path: &Path) -> bool {
810    path.join("include/dr_api.h").is_file()
811        || path.join("DynamoRIOConfig.cmake").is_file()
812        || path.join("cmake/DynamoRIOConfig.cmake").is_file()
813}
814
815#[cfg(feature = "dbt")]
816fn dynamorio_sdk_available() -> bool {
817    if hermit_resources::resource("dynamorio/bin64/drrun")
818        .is_ok_and(|path| path.is_some_and(|path| path.is_file()))
819    {
820        return true;
821    }
822    if reverie_dbt::bundled_drrun_path().is_file() {
823        return true;
824    }
825    const DEFAULT_ROOTS: [&str; 3] = [
826        "/usr/lib/cmake/DynamoRIO",
827        "/usr/local/lib/cmake/DynamoRIO",
828        "/opt/dynamorio",
829    ];
830
831    ["DYNAMORIO_HOME", "DynamoRIO_DIR"]
832        .into_iter()
833        .filter_map(std::env::var_os)
834        .map(PathBuf::from)
835        .chain(DEFAULT_ROOTS.into_iter().map(PathBuf::from))
836        .any(|path| is_dynamorio_sdk(&path))
837}
838
839#[cfg(feature = "dbt")]
840fn dbt_runtime_unavailable_reason() -> Option<String> {
841    dbt_runtime_unavailable_reason_from(detcore_dbt::runtime_library_path())
842}
843
844#[cfg(feature = "dbt")]
845fn dbt_runtime_unavailable_reason_from(runtime: io::Result<PathBuf>) -> Option<String> {
846    runtime.err().map(|error| {
847        format!(
848            "the Detcore DBT runtime is unavailable: {error}; build the hermit binary and \
849             cdylib in the same target directory"
850        )
851    })
852}
853
854// AUTONOMOUS-BOT-IMPLEMENTED
855// TODO-HUMAN-REVIEW(#688): Review LiteInst runtime discovery.
856/// Checks that `path` is an x86-64 shared object that exports every name in
857/// `required` and registers `initializer_name` in its constructor array, so
858/// that preloading it runs that initializer. `label` names the library in every
859/// error message. Returns the canonical path.
860/// Detcore requires its protected root and sole local RELATIVE registration;
861/// this is minimal discovery, separate from complete artifact qualification.
862fn validate_preload_constructor_library(
863    path: &Path,
864    label: &str,
865    required: &[&str],
866    initializer_name: &str,
867) -> io::Result<PathBuf> {
868    let bytes = fs::read(path).map_err(|error| {
869        io::Error::new(
870            error.kind(),
871            format!("failed to read {label} {}: {error}", path.display()),
872        )
873    })?;
874    let elf = Elf::parse(&bytes).map_err(|error| {
875        io::Error::new(
876            io::ErrorKind::InvalidData,
877            format!("{label} {} is not an ELF DSO: {error}", path.display()),
878        )
879    })?;
880    if elf.header.e_type != header::ET_DYN || elf.header.e_machine != header::EM_X86_64 {
881        return Err(io::Error::new(
882            io::ErrorKind::InvalidData,
883            format!("{label} {} is not an x86-64 shared object", path.display()),
884        ));
885    }
886
887    for &name in required {
888        if !elf
889            .dynsyms
890            .iter()
891            .any(|symbol| elf.dynstrtab.get_at(symbol.st_name) == Some(name))
892        {
893            return Err(io::Error::new(
894                io::ErrorKind::InvalidData,
895                format!(
896                    "{label} {} is missing required export {name}",
897                    path.display()
898                ),
899            ));
900        }
901    }
902    if initializer_name == liteinst_constructor::ROOT {
903        liteinst_constructor::validate(&bytes, &elf).map_err(|error| {
904            io::Error::new(
905                error.kind(),
906                format!(
907                    "{label} {} has invalid Detcore constructor binding: {error}",
908                    path.display()
909                ),
910            )
911        })?;
912        return path.canonicalize();
913    }
914    let (initializer_index, initializer) = elf
915        .dynsyms
916        .iter()
917        .enumerate()
918        .find(|(_, symbol)| elf.dynstrtab.get_at(symbol.st_name) == Some(initializer_name))
919        .ok_or_else(|| {
920            io::Error::other(format!(
921                "checked {label} initializer {initializer_name} disappeared"
922            ))
923        })?;
924    let init_array = elf
925        .section_headers
926        .iter()
927        .find(|section| section.sh_type == section_header::SHT_INIT_ARRAY)
928        .ok_or_else(|| {
929            io::Error::new(
930                io::ErrorKind::InvalidData,
931                format!("{label} {} has no constructor array", path.display()),
932            )
933        })?;
934    let init_start = init_array.sh_addr;
935    let init_end = init_start.saturating_add(init_array.sh_size);
936    let relocated_initializer = elf
937        .dynrelas
938        .iter()
939        .chain(elf.dynrels.iter())
940        .any(|relocation| {
941            (init_start..init_end).contains(&relocation.r_offset)
942                && relocation.r_sym == initializer_index
943        });
944    let init_bytes = usize::try_from(init_array.sh_offset)
945        .ok()
946        .and_then(|start| {
947            usize::try_from(init_array.sh_size)
948                .ok()
949                .and_then(|size| bytes.get(start..start.checked_add(size)?))
950        })
951        .unwrap_or_default();
952    let direct_initializer = init_bytes
953        .as_chunks::<8>()
954        .0
955        .iter()
956        .any(|entry| u64::from_le_bytes(*entry) == initializer.st_value);
957    if !relocated_initializer && !direct_initializer {
958        return Err(io::Error::new(
959            io::ErrorKind::InvalidData,
960            format!(
961                "{label} {} does not register {initializer_name} as a preload constructor",
962                path.display()
963            ),
964        ));
965    }
966    path.canonicalize()
967}
968
969/// Environment variable naming the in-guest Detcore preload
970/// (`libdetcore_liteinst.so`) explicitly.
971pub const LITEINST_TOOL_RUNTIME_ENV: &str = "HERMIT_LITEINST_TOOL_RUNTIME";
972
973// AUTONOMOUS-BOT-IMPLEMENTED
974// TODO-HUMAN-REVIEW(PR-3635): Review in-guest Detcore runtime discovery.
975/// Returns the in-guest Detcore preload: the one [`LITEINST_TOOL_RUNTIME_ENV`]
976/// names; otherwise the packaged `rsrcs/libdetcore_liteinst.so` of the selected
977/// Hermit installation (`hermit-install` stages it, as it stages the DBT and
978/// SaBRe Detcore runtimes, and a standalone installation or published bundle
979/// carries it). A selected installation missing that resource is incomplete
980/// and is refused. When no installation is selected, the development fallback
981/// is the one `cargo build -p detcore-liteinst` built beside the Hermit binary
982/// or in its `deps/` directory.
983///
984/// A runtime built from another tree is refused when it starts: Hermit passes
985/// it [`detcore::config_wire_fingerprint`], which it compares with its own
986/// before decoding anything (<https://github.com/rrnewton/hermit/issues/3986>).
987#[doc(hidden)]
988pub fn liteinst_tool_runtime_library_path() -> io::Result<PathBuf> {
989    if let Some(path) = std::env::var_os(LITEINST_TOOL_RUNTIME_ENV) {
990        let path = PathBuf::from(path);
991        if !path.is_file() {
992            return Err(io::Error::new(
993                io::ErrorKind::NotFound,
994                format!("{LITEINST_TOOL_RUNTIME_ENV} does not name a regular file"),
995            ));
996        }
997        return validate_liteinst_tool_runtime_library(&path).map_err(|error| {
998            io::Error::new(
999                error.kind(),
1000                format!("{LITEINST_TOOL_RUNTIME_ENV} is invalid: {error}"),
1001            )
1002        });
1003    }
1004
1005    if let Some(path) = hermit_resources::resource("libdetcore_liteinst.so")? {
1006        if !path.is_file() {
1007            return Err(io::Error::new(
1008                io::ErrorKind::NotFound,
1009                "selected Hermit installation has no finalized in-guest Detcore runtime; \
1010                 run `make install-deps` to build and stage the qualified LiteInst runtime",
1011            ));
1012        }
1013        return validate_liteinst_tool_runtime_library(&path);
1014    }
1015
1016    let executable = std::env::current_exe()?;
1017    let directory = executable.parent().ok_or_else(|| {
1018        io::Error::new(
1019            io::ErrorKind::NotFound,
1020            "Hermit executable has no parent directory",
1021        )
1022    })?;
1023    if let Some(path) = [
1024        directory.join("libdetcore_liteinst.so"),
1025        directory.join("deps/libdetcore_liteinst.so"),
1026    ]
1027    .into_iter()
1028    .find(|path| path.is_file())
1029    {
1030        return validate_liteinst_tool_runtime_library(&path);
1031    }
1032    Err(io::Error::new(
1033        io::ErrorKind::NotFound,
1034        format!(
1035            "libdetcore_liteinst.so was not built beside {} or staged as an installed resource",
1036            executable.display()
1037        ),
1038    ))
1039}
1040
1041fn validate_liteinst_tool_runtime_library(path: &Path) -> io::Result<PathBuf> {
1042    validate_preload_constructor_library(
1043        path,
1044        "in-guest Detcore runtime",
1045        &["detcore_liteinst_initialize"],
1046        "detcore_liteinst_initialize",
1047    )
1048}
1049
1050// AUTONOMOUS-BOT-IMPLEMENTED
1051// TODO-HUMAN-REVIEW(PR-3635): Review the in-guest LiteInst library refusals.
1052/// In-guest LiteInst refused a run before starting its guest, because the
1053/// runtime cannot honour the request or could not monitor the program.
1054///
1055/// A type rather than a message, because it crosses the container error
1056/// boundary as [`error::FailureKind::PolicyRefusal`] (exit 122).
1057#[derive(Debug, Clone, PartialEq, Eq)]
1058pub struct LiteinstInGuestRefusal {
1059    backend: Backend,
1060    reason: String,
1061}
1062
1063impl LiteinstInGuestRefusal {
1064    /// A refusal of a `--backend=liteinst` run.
1065    pub fn new(reason: impl Into<String>) -> Self {
1066        Self::for_backend(Backend::Liteinst, reason)
1067    }
1068
1069    /// A refusal of a run of `backend`, one of the in-guest LiteInst backends
1070    /// ([`Backend::is_in_guest_liteinst`]), so the message names the backend
1071    /// the caller selected.
1072    pub fn for_backend(backend: Backend, reason: impl Into<String>) -> Self {
1073        debug_assert!(backend.is_in_guest_liteinst(), "{backend:?}");
1074        Self {
1075            backend,
1076            reason: reason.into(),
1077        }
1078    }
1079}
1080
1081impl std::fmt::Display for LiteinstInGuestRefusal {
1082    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1083        let runtime = match self.backend {
1084            Backend::InGuestTrap => "in-guest LiteInst, site patching off",
1085            _ => "in-guest LiteInst",
1086        };
1087        write!(
1088            f,
1089            "--backend={} ({runtime}) refuses this run: {}",
1090            self.backend.as_str(),
1091            self.reason
1092        )
1093    }
1094}
1095
1096impl std::error::Error for LiteinstInGuestRefusal {}
1097
1098/// Refuses, before the guest starts, an in-guest LiteInst run that the runtime
1099/// cannot honour or could not monitor.
1100///
1101/// - A maximum timeslice. Reverie's in-guest Tool host has no preemption timer:
1102///   its `set_timer` refuses with `ENOSYS`, and Detcore treats a failed
1103///   `set_timer` as fatal (`.expect("Failed to set timer")`), so the guest
1104///   would panic at its first scheduling point. The CLI refuses
1105///   `--max-timeslice` earlier; this covers library callers.
1106/// - A kernel older than Linux 6.5 ([`in_guest_liteinst_kernel_gap`]).
1107/// - A guest program that would run code before, or without, the runtime's
1108///   constructor ([`in_guest_liteinst_program_gap`]).
1109/// - For `in-guest-trap`, a guest environment that sets
1110///   `REVERIE_LITEINST_SITE_PATCHING` to anything but `0`
1111///   ([`in_guest_trap_site_patching_conflict`]).
1112///
1113/// This runs where the guest is spawned (inside the container for the CLI),
1114/// so it resolves the program in the filesystem the guest sees. It pins the
1115/// resolved program on `command` ([`pin_spawn_program`]), so the launch
1116/// executes the same path this check inspected. For `in-guest-trap` it then
1117/// sets `REVERIE_LITEINST_SITE_PATCHING=0` on `command`
1118/// ([`force_in_guest_site_patching`]).
1119#[cfg(feature = "liteinst")]
1120fn refuse_in_guest_liteinst_run(
1121    command: &mut Command,
1122    config: &DetConfig,
1123    backend: Backend,
1124) -> Result<(), Error> {
1125    let reason = if let Some(conflict) = in_guest_trap_site_patching_conflict(command, backend) {
1126        Some(conflict)
1127    } else if config.max_timeslice.is_some() {
1128        Some(
1129            "it cannot deliver Detcore's preemption timer yet (the in-guest Tool host refuses \
1130             set_timer with ENOSYS), so the run would fail at its first timeslice; pass \
1131             --max-timeslice=disabled"
1132                .to_owned(),
1133        )
1134    } else if let Some(gap) = in_guest_liteinst_kernel_gap(&running_kernel_release()) {
1135        Some(gap)
1136    } else {
1137        in_guest_liteinst_program_gap(command)?
1138    };
1139    match reason {
1140        Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
1141            backend, reason,
1142        ))),
1143        None => {
1144            force_in_guest_site_patching(command, backend);
1145            Ok(())
1146        }
1147    }
1148}
1149
1150/// The value of `REVERIE_LITEINST_SITE_PATCHING` (`reverie_liteinst::SITE_PATCHING_ENV`)
1151/// that the guest sees under `backend`, when Hermit decides it: `0` for
1152/// `in-guest-trap`, which exists to run with no syscall site patched, and
1153/// `None` for `liteinst`, which leaves the variable to the guest environment
1154/// (unset means patching on).
1155pub fn forced_site_patching_value(backend: Backend) -> Option<&'static str> {
1156    match backend {
1157        Backend::InGuestTrap => Some("0"),
1158        _ => None,
1159    }
1160}
1161
1162/// Why an `in-guest-trap` run cannot start with the guest environment of
1163/// `command`: the environment (explicit or inherited) sets
1164/// `REVERIE_LITEINST_SITE_PATCHING` to a value other than the one Hermit
1165/// forces. Hermit refuses such a run rather than overriding the value
1166/// silently, because the caller asked for two contradictory things: site
1167/// patching (or a value the runtime would reject) and the backend that exists
1168/// to run without it. A value equal to the forced one is accepted. `None`
1169/// for every other backend.
1170#[cfg(feature = "liteinst")]
1171fn in_guest_trap_site_patching_conflict(command: &Command, backend: Backend) -> Option<String> {
1172    let forced = forced_site_patching_value(backend)?;
1173    let name = reverie_liteinst::SITE_PATCHING_ENV;
1174    let value = command.get_env(name)?;
1175    (*value != *std::ffi::OsStr::new(forced)).then(|| {
1176        format!(
1177            "the guest environment sets {name}={}, but --backend={} runs with syscall site \
1178             patching off and sets {name}={forced} itself; drop the variable, or select \
1179             --backend=liteinst to patch syscall sites",
1180            value.to_string_lossy(),
1181            backend.as_str()
1182        )
1183    })
1184}
1185
1186/// Sets the guest's `REVERIE_LITEINST_SITE_PATCHING` to the value Hermit
1187/// forces for `backend` ([`forced_site_patching_value`]), leaving the
1188/// environment unchanged for a backend that forces none. The guest's
1189/// descendants inherit it unless the guest changes its own environment; a
1190/// descendant that turns patching back on shows in the run's dispatch record
1191/// as patched sites.
1192#[cfg(feature = "liteinst")]
1193fn force_in_guest_site_patching(command: &mut Command, backend: Backend) {
1194    if let Some(value) = forced_site_patching_value(backend) {
1195        command.env(reverie_liteinst::SITE_PATCHING_ENV, value);
1196    }
1197}
1198
1199/// Whether every in-guest Tool image of a `backend` run checks that its runtime
1200/// captured site patching off and statistics on
1201/// (`detcore::Config::in_guest_site_patching_off`): true for `in-guest-trap`.
1202#[cfg(feature = "liteinst")]
1203fn in_guest_site_patching_off(backend: Backend) -> bool {
1204    forced_site_patching_value(backend) == Some("0")
1205}
1206
1207/// Whether an in-guest run of `backend` collects LiteInst's statistics: when
1208/// something reads them ([`backend_stats::request`]), and on every
1209/// `in-guest-trap` run, whose result is checked against them
1210/// ([`in_guest_trap_patching_evidence`]).
1211#[cfg(feature = "liteinst")]
1212fn in_guest_stats_request(
1213    backend: Backend,
1214    summary_json: &Option<PathBuf>,
1215) -> reverie::BackendStatsRequest {
1216    if backend == Backend::InGuestTrap {
1217        reverie::BackendStatsRequest::ENABLED
1218    } else {
1219        backend_stats::request(summary_json)
1220    }
1221}
1222
1223/// Reports a refusal the fail-closed policy decided inside the guest as
1224/// Hermit's own refusal. The in-guest Detcore that refuses tells the
1225/// coordinator why (`GlobalState::policy_refusal`) and exits with
1226/// `HERMIT_POLICY_REFUSAL_EXIT`, which ends only the guest process. Without
1227/// this the run ended with that as the guest's exit status and no reason, or
1228/// with whatever postcondition the early exit then tripped (an unregistered
1229/// exit, or in-guest-trap's missing statistics). Checked before those.
1230#[cfg(feature = "liteinst")]
1231fn refuse_in_guest_policy(backend: Backend, refusal: Option<String>) -> Result<(), Error> {
1232    match refusal {
1233        Some(reason) => Err(Error::new(LiteinstInGuestRefusal::for_backend(
1234            backend,
1235            format!("{reason}; --backend=ptrace runs this program"),
1236        ))),
1237        None => Ok(()),
1238    }
1239}
1240
1241/// Why a finished `in-guest-trap` run did not show that it ran with syscall
1242/// site patching off, from its dispatch record and the number of guest
1243/// processes that reported LiteInst statistics: a site the runtime patched or
1244/// considered patching (with patching off it considers none), no record, or no
1245/// process report at all, in which case the record's zeros are not
1246/// measurements (a run whose guests collected no statistics still yields an
1247/// empty record). `None` for every other backend.
1248///
1249/// This is the coordinator's postcondition. Each Tool image also refuses to
1250/// run its program when the runtime started it with patching on
1251/// (`detcore::in_guest_site_patching`), which holds for every image whatever
1252/// it reports; this one sees only the images that report, because an image
1253/// reports its statistics when it exits (`exit` or `exit_group`), so an image
1254/// that `execve`s, or is killed by a signal, sends none, and the coordinator
1255/// cannot tell that from a report that was suppressed. It refuses a run in
1256/// which no process reported; it does not detect a run in which some did and
1257/// others did not. Each image's own check covers that: an image whose runtime
1258/// is not collecting statistics refuses to run its program.
1259#[cfg(feature = "liteinst")]
1260fn in_guest_trap_patching_evidence(
1261    backend: Backend,
1262    dispatch: Option<&reverie::DispatchStats>,
1263    process_reports: u64,
1264) -> Option<String> {
1265    if backend != Backend::InGuestTrap {
1266        return None;
1267    }
1268    let Some(record) = dispatch else {
1269        return Some(
1270            "the run produced no LiteInst dispatch record, so it cannot show that no syscall \
1271             site was patched"
1272                .to_owned(),
1273        );
1274    };
1275    if process_reports == 0 {
1276        return Some(
1277            "no guest process reported LiteInst statistics, so the run's zero patched sites \
1278             are not a measurement and it cannot show that no syscall site was patched"
1279                .to_owned(),
1280        );
1281    }
1282    let shown =
1283        |count: Option<u64>| count.map_or_else(|| "unmeasured".to_owned(), |n| n.to_string());
1284    (record.sites.patched != Some(0) || record.sites.candidates != Some(0)).then(|| {
1285        format!(
1286            "its guests' LiteInst statistics report {} patched and {} candidate syscall sites, \
1287             so it did not run with syscall site patching off and its result is not an \
1288             in-guest-trap result",
1289            shown(record.sites.patched),
1290            shown(record.sites.candidates)
1291        )
1292    })
1293}
1294
1295/// Refuses a finished `in-guest-trap` run whose dispatch record shows site
1296/// patching ([`in_guest_trap_patching_evidence`]): records a determinism loss,
1297/// so verification refuses to compare it, and returns the typed in-guest
1298/// refusal (exit 122).
1299#[cfg(feature = "liteinst")]
1300fn refuse_in_guest_trap_patching(backend: Backend, evidence: Option<String>) -> Result<(), Error> {
1301    match evidence {
1302        Some(reason) => {
1303            detcore::detlog::record_determinism_loss(&reason);
1304            Err(Error::new(LiteinstInGuestRefusal::for_backend(
1305                backend, reason,
1306            )))
1307        }
1308        None => Ok(()),
1309    }
1310}
1311
1312/// Use the existing actual subscriber-derived forwarding policy for the
1313/// shared native path. Call inside the same verification tracing scope.
1314#[cfg(feature = "native-exec")]
1315#[doc(hidden)]
1316pub fn in_guest_detlog_forward_policy_for_native() -> detcore::detlog::ForwardPolicy {
1317    in_guest_detlog_forward_policy()
1318}
1319
1320/// Report the shared native trap runtime through the existing statistics
1321/// comparator and require a real guest report with site patching disabled.
1322/// This never converts a patching-off execution into LiteInst evidence.
1323#[cfg(feature = "liteinst")]
1324#[doc(hidden)]
1325pub fn native_trap_dispatch_stats(
1326    source: &reverie_liteinst::LiteinstBackendStatsSource,
1327) -> Result<Option<reverie::DispatchStats>, Error> {
1328    let backend = Backend::InGuestTrap;
1329    let record = backend_stats::report(backend, reverie::BackendStatsRequest::ENABLED, source);
1330    let evidence = in_guest_trap_patching_evidence(
1331        backend,
1332        record.as_ref(),
1333        source.snapshot().process_reports(),
1334    );
1335    refuse_in_guest_trap_patching(backend, evidence)?;
1336    Ok(record)
1337}
1338
1339/// The oldest kernel in-guest LiteInst runs on, as (major, minor). Linux 6.5
1340/// added `SO_PEERPIDFD`: the coordinator admits each guest process through the
1341/// pidfd of the socket's peer and watches that pidfd for the process's exit
1342/// (`in_guest_exits`). On an older kernel every admission would fail.
1343#[cfg(feature = "liteinst")]
1344const IN_GUEST_LITEINST_KERNEL_FLOOR: (u32, u32) = (6, 5);
1345
1346/// The running kernel's release string (`uname -r`), or empty if unreadable.
1347#[cfg(feature = "liteinst")]
1348fn running_kernel_release() -> String {
1349    let mut name: libc::utsname = unsafe { std::mem::zeroed() };
1350    // SAFETY: uname fills the struct it is given.
1351    if unsafe { libc::uname(&mut name) } != 0 {
1352        return String::new();
1353    }
1354    // SAFETY: uname NUL-terminates each field.
1355    unsafe { std::ffi::CStr::from_ptr(name.release.as_ptr()) }
1356        .to_string_lossy()
1357        .into_owned()
1358}
1359
1360/// Why kernel `release` cannot run in-guest LiteInst, or `None` when it is at
1361/// least [`IN_GUEST_LITEINST_KERNEL_FLOOR`]. A release whose version cannot be
1362/// read is refused.
1363#[cfg(feature = "liteinst")]
1364fn in_guest_liteinst_kernel_gap(release: &str) -> Option<String> {
1365    let mut numbers = release
1366        .split(|c: char| !c.is_ascii_digit())
1367        .map(|part| part.parse::<u32>().ok());
1368    let (floor_major, floor_minor) = IN_GUEST_LITEINST_KERNEL_FLOOR;
1369    match (numbers.next().flatten(), numbers.next().flatten()) {
1370        (Some(major), Some(minor)) if (major, minor) >= IN_GUEST_LITEINST_KERNEL_FLOOR => None,
1371        (Some(_), Some(_)) => Some(format!(
1372            "it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD, which it uses to \
1373             admit each guest process and observe its exit); this kernel is {release}"
1374        )),
1375        _ => Some(format!(
1376            "it needs Linux {floor_major}.{floor_minor} or later (SO_PEERPIDFD), and the kernel \
1377             release {release:?} does not say which version this is"
1378        )),
1379    }
1380}
1381
1382/// How many `#!` interpreters [`in_guest_liteinst_program_gap`] follows before
1383/// it refuses the program. The kernel has its own small limit (`exec_binprm` in
1384/// `fs/exec.c`); a chain this check stops following is refused, not run, so the
1385/// check fails closed whichever limit is lower.
1386#[cfg(feature = "liteinst")]
1387const MAX_INTERPRETER_DEPTH: usize = 4;
1388
1389/// Why the guest program would run code before, or without, the in-guest
1390/// runtime, or `None` when it would not.
1391///
1392/// The runtime is an `LD_PRELOAD` library whose constructor installs Detcore.
1393/// The dynamic loader never loads it into a statically linked image or an image
1394/// of another architecture, and ignores `LD_PRELOAD` in secure-execution mode
1395/// (set-user-ID, set-group-ID, or file capabilities). An executable's
1396/// `DT_PREINIT_ARRAY` runs before every library constructor. Each of those
1397/// would run guest code unmonitored, so each is refused. `#!` scripts are
1398/// checked through their interpreter, read as the kernel's script handler
1399/// reads it ([`script::KernelScript`]). A program or interpreter that is not a
1400/// regular file is refused before it is opened: the kernel executes only
1401/// regular files, opening a device can act on it, opening a socket fails, and
1402/// reading a FIFO that has no writer would block the check.
1403///
1404/// Every fact about one file (its type, header, ELF headers, mode bits and
1405/// capabilities) is read through one open descriptor, so they all describe
1406/// the same file. The check is still advisory, not containment: the `execve`
1407/// opens the path again, and a file replaced at that path in between is not
1408/// checked again.
1409///
1410/// Not covered, and recorded on
1411/// <https://github.com/rrnewton/hermit/issues/3520>:
1412/// - The loader itself, the C library's initialization, the executable's
1413///   `IFUNC` resolvers and the constructors of the executable's own shared
1414///   libraries all run before the runtime's constructor in every guest.
1415/// - Secure-execution mode that a security module or a parent with differing
1416///   real and effective IDs imposes; only the file's own mode bits and
1417///   capabilities are checked.
1418/// - Whether the `PT_INTERP` loader honours `LD_PRELOAD` at all.
1419/// - A `binfmt_misc` rule, which the kernel consults before its ELF and script
1420///   handlers, and which can hand a file this check accepted to another
1421///   interpreter (for example an emulator).
1422/// - A runtime library the loader fails to load: the loader continues without
1423///   it, and only the launch's check that the guest connected before it exited
1424///   reports the failure, after the guest ran.
1425/// - A `pre_exec` callback on `command` that changes the working directory or
1426///   the root directory: the check resolves paths against the working
1427///   directory `command` is configured with, in Hermit's root, before any
1428///   such callback runs.
1429#[cfg(feature = "liteinst")]
1430fn in_guest_liteinst_program_gap(command: &mut Command) -> Result<Option<String>, Error> {
1431    use std::io::Read;
1432    use std::os::unix::fs::OpenOptionsExt;
1433
1434    use script::KernelScript;
1435
1436    let mut path = pin_spawn_program(command)?;
1437    for _ in 0..=MAX_INTERPRETER_DEPTH {
1438        let shown = path.display().to_string();
1439        let not_regular = || {
1440            Ok(Some(format!(
1441                "{shown} is not a regular file, and the kernel executes only regular files"
1442            )))
1443        };
1444        if !fs::metadata(&path)
1445            .with_context(|| format!("cannot read guest program {shown}"))?
1446            .is_file()
1447        {
1448            return not_regular();
1449        }
1450        // The path can change type after the check above. O_NONBLOCK then keeps
1451        // the open of a FIFO that has no writer from blocking, and O_NOCTTY
1452        // keeps a terminal from becoming Hermit's controlling terminal; neither
1453        // changes how a regular file is read. The descriptor's own type is
1454        // checked again below.
1455        let mut file = fs::OpenOptions::new()
1456            .read(true)
1457            .custom_flags(libc::O_NONBLOCK | libc::O_NOCTTY)
1458            .open(&path)
1459            .with_context(|| format!("cannot read guest program {shown}"))?;
1460        if !file
1461            .metadata()
1462            .with_context(|| format!("cannot read guest program {shown}"))?
1463            .is_file()
1464        {
1465            return not_regular();
1466        }
1467        let mut header = Vec::new();
1468        (&file)
1469            .take(256)
1470            .read_to_end(&mut header)
1471            .with_context(|| format!("cannot read guest program {shown}"))?;
1472        match KernelScript::from_buf(&header) {
1473            KernelScript::Interpreter(interpreter) => {
1474                // The kernel opens a relative interpreter against the working
1475                // directory of the process calling execve.
1476                path = match command.get_current_dir() {
1477                    Some(directory) => directory.join(interpreter),
1478                    None => interpreter,
1479                };
1480                continue;
1481            }
1482            KernelScript::Declined => {
1483                return Ok(Some(format!(
1484                    "{shown} starts with #! but the kernel's script handler declines it (it \
1485                     names no interpreter, or the interpreter path fills the first 256 bytes), \
1486                     so the kernel would fail the execve or hand the file to another handler \
1487                     that need not load the runtime"
1488                )));
1489            }
1490            KernelScript::NotScript => {}
1491        }
1492        let Some(startup) = interp::elf_startup(&mut file)
1493            .with_context(|| format!("cannot read the ELF headers of guest program {shown}"))?
1494        else {
1495            return Ok(Some(format!(
1496                "{shown} is neither an ELF executable nor a #! script, so the kernel would hand \
1497                 it to a handler that need not load the runtime"
1498            )));
1499        };
1500        let reason = if !startup.x86_64 {
1501            "is not a 64-bit x86-64 ELF image, so the dynamic loader cannot load the 64-bit \
1502             runtime into it"
1503        } else if !startup.has_interp {
1504            "is statically linked (it has no PT_INTERP), so no dynamic loader runs to load the \
1505             runtime"
1506        } else if is_secure_execution_image(&file, &shown)? {
1507            "is set-user-ID, set-group-ID or has file capabilities, so the kernel runs it in \
1508             secure-execution mode, where the dynamic loader ignores LD_PRELOAD"
1509        } else if startup.has_preinit_array {
1510            "has a DT_PREINIT_ARRAY, whose functions run before the runtime's constructor"
1511        } else {
1512            return Ok(None);
1513        };
1514        return Ok(Some(format!(
1515            "guest program {shown} {reason}, so it would run unmonitored if Hermit launched it"
1516        )));
1517    }
1518    Ok(Some(format!(
1519        "the #! interpreters of guest program {} nest more than {MAX_INTERPRETER_DEPTH} deep",
1520        Path::new(command.get_program()).display()
1521    )))
1522}
1523
1524/// Resolves the program `command` executes with Reverie's
1525/// [`Command::find_program`], the call the in-guest launch makes, and pins the
1526/// result on `command`, keeping `argv[0]`.
1527///
1528/// The result is absolute, so the launch's own `find_program` returns it
1529/// unchanged and the launch executes the same path the check inspected,
1530/// whatever `PATH` or working directory either side would otherwise use. The
1531/// path, not its contents: a file replaced at that path in between is not
1532/// checked again (see [`in_guest_liteinst_program_gap`]). A program the launch
1533/// could not find is an error here, as it would be at launch.
1534#[cfg(feature = "liteinst")]
1535fn pin_spawn_program(command: &mut Command) -> Result<PathBuf, Error> {
1536    let arg0 = command.get_arg0().to_owned();
1537    let program = command.find_program().with_context(|| {
1538        format!(
1539            "cannot find guest program {}",
1540            Path::new(command.get_program()).display()
1541        )
1542    })?;
1543    command.program(&program).arg0(arg0);
1544    Ok(program)
1545}
1546
1547/// Whether executing `file` (shown as `shown`) puts the kernel in
1548/// secure-execution mode (`AT_SECURE`): set-user-ID, set-group-ID (with group
1549/// execute, as the kernel requires), or a `security.capability` attribute.
1550#[cfg(feature = "liteinst")]
1551fn is_secure_execution_image(file: &fs::File, shown: &str) -> Result<bool, Error> {
1552    let mode = file
1553        .metadata()
1554        .with_context(|| format!("cannot stat guest program {shown}"))?
1555        .permissions()
1556        .mode();
1557    if mode & 0o4000 != 0 || mode & 0o2010 == 0o2010 {
1558        return Ok(true);
1559    }
1560    // SAFETY: the descriptor is open for the call, the name is NUL-terminated,
1561    // and a zero-sized query writes no value.
1562    let size = unsafe {
1563        libc::fgetxattr(
1564            file.as_raw_fd(),
1565            c"security.capability".as_ptr(),
1566            std::ptr::null_mut(),
1567            0,
1568        )
1569    };
1570    if size >= 0 {
1571        return Ok(true);
1572    }
1573    match io::Error::last_os_error().raw_os_error() {
1574        Some(libc::ENODATA) | Some(libc::ENOTSUP) => Ok(false),
1575        _ => Err(Error::new(io::Error::last_os_error()).context(format!(
1576            "cannot read the file capabilities of guest program {shown}"
1577        ))),
1578    }
1579}
1580
1581/// Refuses a wall-clock bound on an in-guest LiteInst run. The bound drops the
1582/// run's future, and dropping it neither kills the guest nor stops the
1583/// blocking task that waits for it.
1584#[cfg(feature = "liteinst")]
1585fn refuse_in_guest_liteinst_timeout(
1586    backend: Backend,
1587    timeout: Option<Duration>,
1588) -> Result<(), Error> {
1589    if backend.is_in_guest_liteinst() && timeout.is_some() {
1590        return Err(Error::new(LiteinstInGuestRefusal::for_backend(
1591            backend,
1592            "a wall-clock timeout has not been qualified for the in-guest runtime, whose run \
1593             future does not kill the guest when it is dropped",
1594        )));
1595    }
1596    Ok(())
1597}
1598
1599#[cfg(not(feature = "liteinst"))]
1600fn refuse_in_guest_liteinst_timeout(
1601    _backend: Backend,
1602    _timeout: Option<Duration>,
1603) -> Result<(), Error> {
1604    Ok(())
1605}
1606
1607#[cfg(feature = "liteinst")]
1608fn liteinst_unavailable_reason() -> Option<String> {
1609    liteinst_runtime_unavailable_reason()
1610}
1611
1612// LiteInst is an experimental backend whose architecture is not settled, so the
1613// published crate leaves it out: `reverie-liteinst` (and through it `liteinst2`)
1614// is an optional dependency behind the `liteinst` feature, which
1615// `third-party-backends` enables for every validation build.
1616#[cfg(not(feature = "liteinst"))]
1617fn liteinst_unavailable_reason() -> Option<String> {
1618    Some(if option_env!("CARGO_PKG_NAME") == Some("hermit-run") {
1619        "this build was compiled without the liteinst backend, which is not included in this registry release; its source-development implementation is on https://github.com/rrnewton/hermit/tree/main. This release has no `liteinst` Cargo feature, and `third-party-backends` does not include LiteInst. LiteInst availability on this machine has not been checked".to_owned()
1620    } else {
1621        "this build was compiled without the liteinst backend: the `liteinst` feature is not enabled; rebuild with `--features liteinst` (or `--features third-party-backends`). This says nothing about whether LiteInst works on this machine -- it has not been checked".to_owned()
1622    })
1623}
1624
1625#[cfg(feature = "liteinst")]
1626fn liteinst_runtime_unavailable_reason() -> Option<String> {
1627    liteinst_tool_runtime_library_path().err().map(|error| {
1628        format!(
1629            "the in-guest Detcore runtime is unavailable: {error}; build it with `cargo build -p detcore-liteinst` in the target directory of this hermit binary, install it as rsrcs/libdetcore_liteinst.so, or name it with {LITEINST_TOOL_RUNTIME_ENV}"
1630        )
1631    })
1632}
1633
1634fn kvm_device_unavailable_reason(path: &Path) -> Option<String> {
1635    fs::OpenOptions::new()
1636        .read(true)
1637        .write(true)
1638        .open(path)
1639        .err()
1640        .map(|error| {
1641            format!(
1642                "cannot open {} read-write: {error}; grant access through the device owner/group \
1643                 or root",
1644                path.display()
1645            )
1646        })
1647}
1648
1649/// Process instrumentation backend used to run a Hermit guest.
1650#[derive(Debug, Clone, Copy, Default, Eq, PartialEq, ValueEnum)]
1651pub enum Backend {
1652    /// Use Reverie's ptrace backend.
1653    #[default]
1654    Ptrace,
1655    /// Use the DynamoRIO backend.
1656    Dbt,
1657    /// Use LiteInst, with Detcore's Tool running inside the guest.
1658    Liteinst,
1659    /// Use in-guest LiteInst with syscall site patching off: the same
1660    /// in-guest Detcore host as `liteinst`, but every trapped syscall reaches
1661    /// the Tool through the seccomp `SIGSYS` fallback and no syscall site is
1662    /// rewritten. Hermit sets `REVERIE_LITEINST_SITE_PATCHING=0` in the
1663    /// guest's environment and refuses a run whose environment asks for any
1664    /// other value.
1665    InGuestTrap,
1666    /// Use the SaBRe static binary rewriting backend.
1667    Sabre,
1668    /// Use the KVM backend.
1669    Kvm,
1670    /// Preprocess the main ELF with e9patch, then use the ptrace runtime.
1671    // TODO-HUMAN-REVIEW(PR-594): Review the CLI-only hybrid backend selection.
1672    E9patch,
1673}
1674
1675/// A requested backend could not start because its required runtime support is absent.
1676///
1677/// Keep this as a typed error until the top-level command records its failure class.
1678/// The human-readable message is for the operator; consumers must use the class line
1679/// emitted by the command rather than matching this prose.
1680#[derive(Debug, Clone, Eq, PartialEq)]
1681pub struct BackendUnavailable {
1682    backend: Backend,
1683    reason: String,
1684}
1685
1686impl BackendUnavailable {
1687    pub fn new(backend: Backend, reason: impl Into<String>) -> Self {
1688        Self {
1689            backend,
1690            reason: reason.into(),
1691        }
1692    }
1693
1694    pub fn backend(&self) -> Backend {
1695        self.backend
1696    }
1697
1698    pub fn reason(&self) -> &str {
1699        &self.reason
1700    }
1701}
1702
1703impl std::fmt::Display for BackendUnavailable {
1704    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1705        write!(
1706            formatter,
1707            "backend `{}` is unavailable: {}",
1708            self.backend.as_str(),
1709            self.reason
1710        )
1711    }
1712}
1713
1714impl std::error::Error for BackendUnavailable {}
1715
1716impl Backend {
1717    const ALL: [Self; 7] = [
1718        Self::Ptrace,
1719        Self::Dbt,
1720        Self::Liteinst,
1721        Self::InGuestTrap,
1722        Self::Sabre,
1723        Self::Kvm,
1724        Self::E9patch,
1725    ];
1726
1727    /// Returns the command-line spelling for this backend.
1728    pub const fn as_str(self) -> &'static str {
1729        match self {
1730            Self::Ptrace => "ptrace",
1731            Self::Dbt => "dbt",
1732            Self::Liteinst => "liteinst",
1733            Self::InGuestTrap => "in-guest-trap",
1734            Self::Sabre => "sabre",
1735            Self::Kvm => "kvm",
1736            Self::E9patch => "e9patch",
1737        }
1738    }
1739
1740    /// Whether this backend hosts Detcore's Tool inside each guest process
1741    /// through the in-guest LiteInst preload runtime: `liteinst` and
1742    /// `in-guest-trap`, which differ only in whether syscall sites are patched.
1743    /// Every refusal, capability and launch step of in-guest LiteInst applies to
1744    /// both.
1745    pub const fn is_in_guest_liteinst(self) -> bool {
1746        matches!(self, Self::Liteinst | Self::InGuestTrap)
1747    }
1748
1749    /// The name of the backend runtime that executes this backend's guest, as
1750    /// its statistics source names itself (`BackendStatsSnapshot::BACKEND_NAME`).
1751    /// `in-guest-trap` runs the in-guest LiteInst runtime, so its statistics come
1752    /// from that runtime's source, which is named `liteinst`.
1753    pub const fn runtime_name(self) -> &'static str {
1754        match self {
1755            Self::InGuestTrap => Self::Liteinst.as_str(),
1756            other => other.as_str(),
1757        }
1758    }
1759
1760    fn uses_ptrace_pmu_timers(self) -> bool {
1761        match self {
1762            Self::Ptrace | Self::E9patch => true,
1763            // In-guest Detcore has no ptrace tracer to arm the PMU timer from.
1764            Self::Liteinst | Self::InGuestTrap | Self::Dbt | Self::Sabre | Self::Kvm => false,
1765        }
1766    }
1767
1768    /// Returns backends whose Hermit integration prerequisites are met.
1769    ///
1770    /// Some integrations use CLI launch adapters rather than direct
1771    /// [`run_with_backend`] dispatch.
1772    pub fn available() -> impl Iterator<Item = Self> {
1773        Self::ALL
1774            .into_iter()
1775            .filter(|backend| backend.is_available())
1776    }
1777
1778    /// Returns whether this backend's integration prerequisites are met.
1779    pub fn is_available(self) -> bool {
1780        self.unavailable_reason().is_none()
1781    }
1782
1783    /// Returns an actionable error when this backend's prerequisites are not met.
1784    pub fn ensure_available(self) -> Result<(), Error> {
1785        self.ensure_available_for(NamespaceUse::Creates)
1786    }
1787
1788    /// [`Backend::ensure_available`] for a run that creates `namespaces`: a
1789    /// `--no-namespace` ptrace run is not refused where only `unshare` of a
1790    /// user namespace is denied, since it never makes that call; the ptrace
1791    /// and seccomp probes still apply.
1792    pub fn ensure_available_for(self, namespaces: NamespaceUse) -> Result<(), Error> {
1793        if let Some(reason) = self.unavailable_reason_for(namespaces) {
1794            Err(Error::new(BackendUnavailable::new(self, reason)))
1795        } else {
1796            Ok(())
1797        }
1798    }
1799
1800    fn unavailable_reason(self) -> Option<String> {
1801        self.unavailable_reason_for(NamespaceUse::Creates)
1802    }
1803
1804    fn unavailable_reason_for(self, namespaces: NamespaceUse) -> Option<String> {
1805        match self {
1806            Self::Ptrace => validate_tracing_environment(namespaces)
1807                .err()
1808                .map(|error| error.to_string()),
1809            Self::Dbt => dbt_unavailable_reason(),
1810            // The same runtime, so the same prerequisites and the same reason.
1811            Self::Liteinst | Self::InGuestTrap => liteinst_unavailable_reason(),
1812            // TODO-HUMAN-REVIEW(#589): Review SaBRe backend availability reporting.
1813            Self::Sabre => sabre_unavailable_reason(),
1814            Self::Kvm => kvm_device_unavailable_reason(Path::new("/dev/kvm")),
1815            Self::E9patch => e9patch_unavailable_reason(),
1816        }
1817    }
1818}
1819
1820struct SkidOvershootReport {
1821    enabled: bool,
1822}
1823
1824/// The backend failed while running the guest, after Hermit launched it: the
1825/// DBT evidence check, a KVM execution failure, a SaBRe guest that never
1826/// reached Detcore. `run --verify` records it as `run_failed` with
1827/// `backend_failure` instead of leaving the `not_run` stamp.
1828///
1829/// It sits in the chain below the message that names the failure, so the
1830/// first `Error:` line is unchanged; it crosses the container error boundary
1831/// as [`error::FailureKind::BackendRunFailure`].
1832#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1833pub struct BackendRunFailure;
1834
1835impl std::fmt::Display for BackendRunFailure {
1836    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1837        f.write_str("the backend failed while running the guest")
1838    }
1839}
1840
1841impl std::error::Error for BackendRunFailure {}
1842
1843/// A ptrace-backed run observed late precise-timer delivery, so Hermit refuses
1844/// to treat the completed execution as deterministic evidence.
1845///
1846/// This is a type rather than a message match because it crosses the container
1847/// error boundary as [`error::FailureKind::PolicyRefusal`].
1848#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1849pub struct SkidOvershootError {
1850    count: u64,
1851}
1852
1853impl SkidOvershootError {
1854    pub fn new(count: u64) -> Self {
1855        assert!(
1856            count > 0,
1857            "a skid-overshoot refusal requires a positive count"
1858        );
1859        Self { count }
1860    }
1861
1862    pub fn count(&self) -> u64 {
1863        self.count
1864    }
1865}
1866
1867impl std::fmt::Display for SkidOvershootError {
1868    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1869        write!(
1870            f,
1871            "observed {} {} report(s); refusing the result because precise PMU timer \
1872             delivery passed its target and deterministic execution was not established",
1873            self.count,
1874            reverie::SKID_OVERSHOOT_MARKER
1875        )
1876    }
1877}
1878
1879impl std::error::Error for SkidOvershootError {}
1880
1881fn take_skid_overshoot_error() -> Option<SkidOvershootError> {
1882    let count = reverie::take_skid_overshoot_count();
1883    (count > 0).then(|| SkidOvershootError::new(count))
1884}
1885
1886impl SkidOvershootReport {
1887    fn begin(enabled: bool) -> Self {
1888        if enabled {
1889            // A previous invocation in this process must not qualify this one.
1890            let _ = reverie::take_skid_overshoot_count();
1891        }
1892        Self { enabled }
1893    }
1894
1895    fn finish<T>(self, result: Result<T, Error>) -> Result<T, Error> {
1896        if !self.enabled {
1897            return result;
1898        }
1899
1900        let Some(overshoot) = take_skid_overshoot_error() else {
1901            return result;
1902        };
1903        match result {
1904            Ok(_) => Err(Error::new(overshoot)),
1905            Err(error) => Err(error.context(overshoot)),
1906        }
1907    }
1908
1909    fn finish_with_count<T>(self, result: Result<T, Error>) -> Result<(T, u64), Error> {
1910        if !self.enabled {
1911            return result.map(|value| (value, 0));
1912        }
1913
1914        let count = reverie::take_skid_overshoot_count();
1915        match result {
1916            Ok(value) => Ok((value, count)),
1917            Err(error) if count > 0 => Err(error.context(SkidOvershootError::new(count))),
1918            Err(error) => Err(error),
1919        }
1920    }
1921}
1922
1923// SaBRe's statistics and RPC support are selected only by `sabre`; the external
1924// loader and Detcore plugin must also be supplied. e9patch preprocessing requires
1925// external `e9tool`/`e9patch` artifacts. Neither path is enabled by default.
1926#[cfg(feature = "sabre")]
1927fn sabre_unavailable_reason() -> Option<String> {
1928    sabre_runtime_unavailable_reason()
1929}
1930
1931#[cfg(not(feature = "sabre"))]
1932fn sabre_unavailable_reason() -> Option<String> {
1933    Some("the `sabre` feature is not enabled in this build; rebuild with `--features sabre` (or `--features third-party-backends`). This says nothing about whether SaBRe works on this machine -- it has not been checked".to_owned())
1934}
1935
1936#[cfg(feature = "e9patch")]
1937fn e9patch_unavailable_reason() -> Option<String> {
1938    // e9patch overlays the rewritten ELF in a mount namespace, so it always
1939    // creates namespaces (run refuses `--backend=e9patch --no-namespace`).
1940    validate_tracing_environment(NamespaceUse::Creates)
1941        .err()
1942        .map(|error| error.to_string())
1943        .or_else(e9patch::unavailable_reason)
1944}
1945
1946#[cfg(not(feature = "e9patch"))]
1947fn e9patch_unavailable_reason() -> Option<String> {
1948    Some("the `e9patch` feature is not enabled in this build; rebuild with `--features e9patch` (or `--features third-party-backends`). This says nothing about whether e9patch works on this machine -- it has not been checked".to_owned())
1949}
1950
1951#[cfg(feature = "dbt")]
1952fn dbt_unavailable_reason() -> Option<String> {
1953    if !dynamorio_sdk_available() {
1954        return Some(
1955            "the DynamoRIO runtime was not found; build target/install_pkg, set HERMIT_INSTALL_DIR, or set DYNAMORIO_HOME/DynamoRIO_DIR to a valid SDK"
1956                .to_owned(),
1957        );
1958    }
1959    dbt_runtime_unavailable_reason()
1960}
1961
1962#[cfg(not(feature = "dbt"))]
1963// TODO-HUMAN-REVIEW(PR-1150): Review the default-on DBT compile-time feature boundary.
1964fn dbt_unavailable_reason() -> Option<String> {
1965    Some(dbt_disabled_build_reason(
1966        option_env!("CARGO_PKG_NAME").unwrap_or("hermit"),
1967    ))
1968}
1969
1970#[cfg(not(feature = "dbt"))]
1971fn dbt_disabled_build_reason(package_name: &str) -> String {
1972    if package_name == "hermit-run" {
1973        "the dbt backend is not included in this registry release; use a source build from https://github.com/rrnewton/hermit with `--features dbt`. The registry's `third-party-backends` feature does not include DBT. DynamoRIO availability on this machine has not been checked".to_owned()
1974    } else {
1975        "the `dbt` feature is not enabled in this source build; rebuild with `--features dbt` (or `--features third-party-backends`). DynamoRIO availability on this machine has not been checked".to_owned()
1976    }
1977}
1978
1979#[cfg(feature = "sabre")]
1980const SABRE_BINARY_ENV: &str = "HERMIT_SABRE_BINARY";
1981
1982#[cfg(feature = "sabre")]
1983fn is_executable_file(path: &Path) -> bool {
1984    fs::metadata(path)
1985        .is_ok_and(|metadata| metadata.is_file() && metadata.permissions().mode() & 0o111 != 0)
1986}
1987
1988// TODO-HUMAN-REVIEW(PR-739): Review SaBRe loader discovery and executable validation.
1989#[cfg(feature = "sabre")]
1990fn resolve_sabre_binary_from(
1991    override_path: Option<&OsStr>,
1992    packaged_path: Option<&Path>,
1993    executable: &Path,
1994    path_env: &OsStr,
1995) -> Result<PathBuf, Error> {
1996    if let Some(requested) = override_path {
1997        if requested.is_empty() {
1998            return Err(anyhow!("{SABRE_BINARY_ENV} is empty"));
1999        }
2000        let path = PathBuf::from(requested);
2001        return is_executable_file(&path)
2002            .then_some(path.clone())
2003            .ok_or_else(|| {
2004                anyhow!(
2005                    "{SABRE_BINARY_ENV}={} is not an executable file",
2006                    path.display()
2007                )
2008            });
2009    }
2010
2011    if let Some(path) = packaged_path
2012        && is_executable_file(path)
2013    {
2014        return Ok(path.to_path_buf());
2015    }
2016
2017    let directory = executable
2018        .parent()
2019        .ok_or_else(|| anyhow!("Hermit executable has no parent directory"))?;
2020    let sibling = directory.join("sabre");
2021    let target_build = directory.parent().map(|target| target.join("sabre/sabre"));
2022
2023    if is_executable_file(&sibling) {
2024        return Ok(sibling);
2025    }
2026    if let Some(candidate) = &target_build
2027        && is_executable_file(candidate)
2028    {
2029        return Ok(candidate.clone());
2030    }
2031    if !path_env.is_empty()
2032        && let Some(candidate) = std::env::split_paths(path_env)
2033            .map(|directory| directory.join("sabre"))
2034            .find(|candidate| is_executable_file(candidate))
2035    {
2036        return Ok(candidate);
2037    }
2038
2039    Err(anyhow!(
2040        "SaBRe executable was not found in the Hermit installation, beside {}, or in PATH; set {} or {SABRE_BINARY_ENV}",
2041        executable.display(),
2042        hermit_resources::INSTALL_DIR_ENV
2043    ))
2044}
2045
2046#[cfg(feature = "sabre")]
2047fn resolve_sabre_binary() -> Result<PathBuf, Error> {
2048    let executable =
2049        std::env::current_exe().context("failed to locate running Hermit executable")?;
2050    let override_path = std::env::var_os(SABRE_BINARY_ENV);
2051    let packaged_path = hermit_resources::resource("sabre")?;
2052    let path_env = std::env::var_os("PATH").unwrap_or_default();
2053    resolve_sabre_binary_from(
2054        override_path.as_deref(),
2055        packaged_path.as_deref(),
2056        &executable,
2057        &path_env,
2058    )
2059}
2060
2061#[cfg(feature = "sabre")]
2062const SABRE_RPC_SOCKET_ENV: &str = "REVERIE_SABRE_HERMIT_RPC_SOCKET";
2063#[cfg(feature = "sabre")]
2064const SABRE_DETLOG_FORWARD_ENV: &str = "REVERIE_SABRE_HERMIT_FORWARD_DETLOG";
2065/// `reverie_sabre::TOOL_OUTPUT_ENV`: the descriptor reverie-sabre protects
2066/// for the in-guest tool's own output. Hermit does not link reverie-sabre.
2067#[cfg(feature = "sabre")]
2068const SABRE_TOOL_OUTPUT_ENV: &str = "REVERIE_SABRE_TOOL_OUTPUT_FD";
2069/// `detcore_liteinst::DETLOG_FORWARD_ENV`; that crate is a preload `cdylib`, so
2070/// Hermit cannot import the constant.
2071#[cfg(feature = "liteinst")]
2072const LITEINST_DETLOG_FORWARD_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG";
2073/// `detcore_liteinst::DETLOG_FORWARD_POLICY_ENV`, for the same reason.
2074#[cfg(feature = "liteinst")]
2075const LITEINST_DETLOG_FORWARD_POLICY_ENV: &str = "HERMIT_LITEINST_FORWARD_DETLOG_POLICY";
2076
2077/// Where in-guest LiteInst and SaBRe runs in this process forward Detcore's
2078/// DETLOG records; see [`forward_in_guest_detlogs_to`].
2079static IN_GUEST_DETLOG_SINK: Mutex<Option<std::os::fd::OwnedFd>> = Mutex::new(None);
2080
2081/// Makes the in-guest LiteInst and SaBRe runs this process starts forward the
2082/// DETLOG records Detcore logs inside the guest to `socket`, the sending end of a Unix
2083/// `SOCK_SEQPACKET` pair. `hermit run --verify` gives each run its own pair and
2084/// reads the records from the other end into that run's log. Each record is one
2085/// message, one line (`detcore::detlog::forwarded_line`).
2086/// A record is forwarded when the CLI's filter logs INFO for its module (see
2087/// [`in_guest_detlog_forward_policy`]); without a socket none are forwarded.
2088#[doc(hidden)]
2089pub fn forward_in_guest_detlogs_to(socket: std::os::fd::OwnedFd) {
2090    *IN_GUEST_DETLOG_SINK.lock().unwrap() = Some(socket);
2091}
2092
2093/// What Hermit tells the in-guest LiteInst runtime, which travels in the
2094/// sealed preload bootstrap rather than the guest's environment
2095/// ([`detcore::in_guest_launch`]), so none of it lands on the guest's initial
2096/// stack or in `/proc/self/environ`:
2097/// - this build's [`detcore::config_wire_fingerprint`], which the runtime
2098///   compares with its own before it decodes the configuration the
2099///   coordinator sends. A runtime built from another tree then fails naming
2100///   both fingerprints and its own path, not with a bare decoding error
2101///   (<https://github.com/rrnewton/hermit/issues/3986>);
2102/// - when `policy` forwards any record, the socket chosen with
2103///   [`forward_in_guest_detlogs_to`] (an inheritable duplicate, which the
2104///   runtime moves to a descriptor Reverie reserves and protects from the
2105///   guest) and the encoded policy, which the guest's Detcore applies to each
2106///   record by its module as each in-process `detlog!` callsite asks tracing.
2107///
2108/// The caller keeps the returned duplicate open until the guest has started.
2109/// Hermit's own variable names are removed from `command`, so a stale value
2110/// cannot reach a runtime that falls back to the environment.
2111#[cfg(feature = "liteinst")]
2112fn in_guest_liteinst_launch(
2113    command: &mut Command,
2114    policy: &detcore::detlog::ForwardPolicy,
2115) -> Result<
2116    (
2117        detcore::in_guest_launch::InGuestLaunch,
2118        Option<std::os::fd::OwnedFd>,
2119    ),
2120    Error,
2121> {
2122    command.env_remove(LITEINST_DETLOG_FORWARD_ENV);
2123    command.env_remove(LITEINST_DETLOG_FORWARD_POLICY_ENV);
2124    command.env_remove(detcore::LITEINST_CONFIG_FINGERPRINT_ENV);
2125    let mut launch = detcore::in_guest_launch::InGuestLaunch {
2126        coordinator_fingerprint: Some(detcore::config_wire_fingerprint()),
2127        ..Default::default()
2128    };
2129    // Asking only whether INFO is on for `detcore`, and then forwarding
2130    // everything, kept records a target-scoped filter drops under ptrace
2131    // (info,detcore::random=warn) and could forward nothing where it keeps
2132    // some (warn,detcore::random=info).
2133    if !policy.forwards_any() {
2134        return Ok((launch, None));
2135    }
2136    let Some(duplicate) = inheritable_in_guest_detlog_socket()? else {
2137        return Ok((launch, None));
2138    };
2139    launch.forward_request = Some(detcore::detlog::tool_output_env_value(
2140        duplicate.as_raw_fd(),
2141    )?);
2142    launch.forward_policy = Some(policy.encode());
2143    Ok((launch, Some(duplicate)))
2144}
2145
2146/// An inheritable duplicate of the socket chosen with
2147/// [`forward_in_guest_detlogs_to`], or `None` when none was chosen. The
2148/// caller passes its number to the guest and keeps it open until the guest
2149/// has started.
2150#[cfg(any(feature = "sabre", feature = "liteinst"))]
2151fn inheritable_in_guest_detlog_socket() -> Result<Option<std::os::fd::OwnedFd>, Error> {
2152    let sink = IN_GUEST_DETLOG_SINK.lock().unwrap();
2153    let Some(socket) = sink.as_ref() else {
2154        return Ok(None);
2155    };
2156    // SAFETY: F_DUPFD on an open descriptor returns a new descriptor or -1.
2157    let duplicate = unsafe { libc::fcntl(socket.as_raw_fd(), libc::F_DUPFD, 3) };
2158    if duplicate < 0 {
2159        return Err(Error::new(std::io::Error::last_os_error())
2160            .context("duplicating the in-guest DETLOG forwarding socket"));
2161    }
2162    // SAFETY: fcntl returned a new descriptor this function now owns.
2163    Ok(Some(unsafe {
2164        std::os::fd::OwnedFd::from_raw_fd(duplicate)
2165    }))
2166}
2167#[cfg(feature = "sabre")]
2168const SABRE_PATH_EVIDENCE_ENV: &str = "HERMIT_SABRE_PATH_EVIDENCE";
2169
2170/// The INFO policy for DETLOG records an in-guest Detcore (SaBRe's plugin,
2171/// in-guest LiteInst) forwards: the current subscriber's answer for every
2172/// target the CLI's `RUST_LOG` names (the text
2173/// `EffectiveFilter::from_default_env` builds every CLI subscriber from) and
2174/// for any other target.
2175#[cfg(any(feature = "sabre", feature = "liteinst"))]
2176fn in_guest_detlog_forward_policy() -> detcore::detlog::ForwardPolicy {
2177    let directives = std::env::var(tracing_subscriber::EnvFilter::DEFAULT_ENV).unwrap_or_default();
2178    detcore::detlog::ForwardPolicy::from_current_subscriber(&directives)
2179}
2180#[cfg(feature = "sabre")]
2181const SABRE_STAGING_DIRECTORY: &str = "/dev/shm";
2182
2183#[cfg(feature = "sabre")]
2184struct StagedSabreProgram {
2185    path: PathBuf,
2186}
2187
2188#[cfg(feature = "sabre")]
2189impl Drop for StagedSabreProgram {
2190    fn drop(&mut self) {
2191        let _ = fs::remove_file(&self.path);
2192    }
2193}
2194
2195#[cfg(feature = "sabre")]
2196fn sabre_program_needs_neutral_name(program: &Path) -> bool {
2197    program
2198        .file_name()
2199        .is_some_and(|name| name.as_bytes().starts_with(b"ld"))
2200}
2201
2202// TODO-HUMAN-REVIEW(PR-845): Review the neutral-name workaround for SaBRe's
2203// dynamic-loader prefix collision.
2204#[cfg(feature = "sabre")]
2205fn stage_sabre_program_in(
2206    program: &Path,
2207    staging_directory: &Path,
2208) -> Result<Option<StagedSabreProgram>, Error> {
2209    if !sabre_program_needs_neutral_name(program) {
2210        return Ok(None);
2211    }
2212
2213    let path = staging_directory.join(format!("hermit-sabre-program-{}", std::process::id()));
2214    let mut source = fs::File::open(program).map_err(|error| {
2215        anyhow!(
2216            "failed to open SaBRe guest executable {} for neutral-name staging: {error}",
2217            program.display()
2218        )
2219    })?;
2220    let mut staged = fs::OpenOptions::new()
2221        .write(true)
2222        .create_new(true)
2223        .mode(0o700)
2224        .open(&path)
2225        .map_err(|error| {
2226            anyhow!(
2227                "failed to stage SaBRe guest executable {} as {}: {error}",
2228                program.display(),
2229                path.display()
2230            )
2231        })?;
2232    if let Err(error) = io::copy(&mut source, &mut staged) {
2233        let _ = fs::remove_file(&path);
2234        return Err(anyhow!(
2235            "failed to stage SaBRe guest executable {} as {}: {error}",
2236            program.display(),
2237            path.display()
2238        ));
2239    }
2240    drop(staged);
2241
2242    Ok(Some(StagedSabreProgram { path }))
2243}
2244
2245// TODO-HUMAN-REVIEW(PR-738): Review controller/plugin artifact separation.
2246#[cfg(feature = "sabre")]
2247fn sabre_runtime_library_path() -> io::Result<PathBuf> {
2248    if let Some(path) = hermit_resources::resource("libdetcore_sabre.so")?
2249        && path.is_file()
2250    {
2251        return Ok(path);
2252    }
2253
2254    let executable = std::env::current_exe()?;
2255    let directory = executable.parent().ok_or_else(|| {
2256        io::Error::new(
2257            io::ErrorKind::NotFound,
2258            "Hermit executable has no parent directory",
2259        )
2260    })?;
2261    [
2262        directory.join("libdetcore_sabre.so"),
2263        directory.join("deps/libdetcore_sabre.so"),
2264    ]
2265    .into_iter()
2266    .find(|path| path.is_file())
2267    .ok_or_else(|| {
2268        io::Error::new(
2269            io::ErrorKind::NotFound,
2270            format!(
2271                "libdetcore_sabre.so was not built beside {}",
2272                executable.display()
2273            ),
2274        )
2275    })
2276}
2277
2278#[cfg(feature = "sabre")]
2279fn sabre_runtime_unavailable_reason() -> Option<String> {
2280    if let Err(error) = resolve_sabre_binary() {
2281        return Some(error.to_string());
2282    }
2283    sabre_runtime_library_path().err().map(|error| {
2284        format!(
2285            "the Detcore SaBRe plugin is unavailable: {error}; build detcore-sabre and hermit in the same target directory"
2286        )
2287    })
2288}
2289
2290// AUTONOMOUS-BOT-IMPLEMENTED
2291// TODO-HUMAN-REVIEW(PR-774): Review the bounded SaBRe RPC disconnect drain.
2292#[cfg(feature = "sabre")]
2293const SABRE_RPC_DISCONNECT_TIMEOUT: Duration = Duration::from_secs(1);
2294
2295#[cfg(feature = "sabre")]
2296async fn wait_for_sabre_rpc_disconnects<T>(
2297    global: &Arc<T>,
2298    timeout: Duration,
2299) -> Result<(), usize> {
2300    let disconnected = tokio::time::timeout(timeout, async {
2301        while Arc::strong_count(global) > 1 {
2302            tokio::time::sleep(Duration::from_millis(1)).await;
2303        }
2304    })
2305    .await;
2306
2307    if disconnected.is_ok() {
2308        return Ok(());
2309    }
2310
2311    let live_references = Arc::strong_count(global).saturating_sub(1);
2312    if live_references == 0 {
2313        Ok(())
2314    } else {
2315        Err(live_references)
2316    }
2317}
2318
2319// AUTONOMOUS-BOT-IMPLEMENTED
2320// TODO-HUMAN-REVIEW(PR-782): Review SaBRe RPC server shutdown errors.
2321#[cfg(feature = "sabre")]
2322async fn stop_sabre_rpc_server<E>(
2323    server_task: tokio::task::JoinHandle<Result<(), E>>,
2324) -> Result<(), Error>
2325where
2326    E: std::fmt::Display,
2327{
2328    server_task.abort();
2329    match server_task.await {
2330        Err(error) if error.is_cancelled() => Ok(()),
2331        Err(error) => Err(anyhow!("SaBRe coordinator task failed: {error}")),
2332        Ok(Err(error)) => Err(anyhow!("SaBRe coordinator server failed: {error}")),
2333        Ok(Ok(())) => Err(anyhow!("SaBRe coordinator server stopped unexpectedly")),
2334    }
2335}
2336
2337// AUTONOMOUS-BOT-IMPLEMENTED
2338// TODO-HUMAN-REVIEW(PR-789): Review complete SaBRe RPC shutdown ordering.
2339#[cfg(feature = "sabre")]
2340async fn shutdown_sabre_rpc<T, E>(
2341    server_task: tokio::task::JoinHandle<Result<(), E>>,
2342    global: &Arc<T>,
2343    timeout: Duration,
2344) -> Result<(), Error>
2345where
2346    E: std::fmt::Display,
2347{
2348    let server_result = stop_sabre_rpc_server(server_task).await;
2349    let disconnect_result = wait_for_sabre_rpc_disconnects(global, timeout).await;
2350
2351    server_result?;
2352    disconnect_result.map_err(|live_references| {
2353        anyhow!("SaBRe coordinator stopped with {live_references} live RPC reference(s)")
2354    })
2355}
2356
2357fn ensure_backend_dispatch(backend: Backend) -> Result<(), Error> {
2358    // The CLI probes ptrace readiness before entering its container; repeating
2359    // the namespace probe here would test nested namespaces instead of the host.
2360    if backend == Backend::Ptrace {
2361        return Ok(());
2362    }
2363    if backend == Backend::E9patch {
2364        return Err(anyhow!(
2365            "backend `e9patch` requires CLI preprocessing; library callers must use \
2366             e9patch::prepare and then select `ptrace`"
2367        ));
2368    }
2369    // KVM and DBT have dedicated dispatches (`run_kvm` and `run_dbt`); neither
2370    // must reach this generic rejection path.
2371    backend.ensure_available()?;
2372    Err(anyhow!(
2373        "backend `{}` has no Hermit dispatch implementation",
2374        backend.as_str()
2375    ))
2376}
2377
2378/// Run one command with the Detcore tool executing inside a SaBRe plugin and
2379/// the single GlobalState held by this Hermit coordinator process.
2380// AUTONOMOUS-BOT-IMPLEMENTED
2381// TODO-HUMAN-REVIEW(PR-738): Review SaBRe coordinator lifetime and artifact loading.
2382#[cfg(feature = "sabre")]
2383async fn run_sabre(
2384    mut command: Command,
2385    config: DetConfig,
2386    print_summary: bool,
2387    print_summary_to_json_file: &Option<PathBuf>,
2388    capture_output: bool,
2389) -> Result<Output, Error> {
2390    let path_evidence_file = std::env::var_os(SABRE_PATH_EVIDENCE_ENV).map(PathBuf::from);
2391    // Whether this run passes the plugin a DETLOG socket (below), in which case
2392    // every Tool image must forward on it; see
2393    // detcore::Config::in_guest_detlog_forward_policy.
2394    let mut config = config;
2395    let policy = in_guest_detlog_forward_policy();
2396    config.in_guest_detlog_forward_policy = (policy.forwards_any()
2397        && IN_GUEST_DETLOG_SINK.lock().unwrap().is_some())
2398    .then(|| policy.encode());
2399    let sabre = resolve_sabre_binary()?;
2400    // The kernel execs SaBRe's loader, which loads the guest itself, so the
2401    // kernel's `exe` link names the loader (`detcore::LaunchImage::launcher`).
2402    // Declared even where the first image could not be resolved, so that a
2403    // link Detcore cannot answer is refused rather than named the loader.
2404    config
2405        .launch_image
2406        .get_or_insert(detcore::LaunchImage {
2407            exe: None,
2408            launcher: None,
2409        })
2410        .launcher = Some(PathBuf::from(&sabre));
2411    let plugin = sabre_runtime_library_path()
2412        .map_err(|error| anyhow!("failed to locate the Detcore SaBRe plugin: {error}"))?;
2413    let program = command.find_program().map_err(|error| {
2414        anyhow!(
2415            "failed to resolve SaBRe guest executable {:?}: {error}",
2416            command.get_program()
2417        )
2418    })?;
2419    let staged_program = stage_sabre_program_in(&program, Path::new(SABRE_STAGING_DIRECTORY))?;
2420    let launch_program = staged_program
2421        .as_ref()
2422        .map_or(program.as_path(), |staged| staged.path.as_path());
2423
2424    let bootstrap_launch =
2425        sabre_bootstrap::Launch::new(Path::new(&sabre), launch_program, &config)?;
2426
2427    // This runs after Hermit enters the guest mount namespace, where `/tmp`
2428    // names the container-visible temporary filesystem. Do not inherit a
2429    // host-side nested TMPDIR: validation commonly sets TMPDIR=/tmp/<run>/tmp,
2430    // but that parent path is hidden once the private `/tmp` mount is active.
2431    // The SaBRe plugin and coordinator must name the socket through the same
2432    // namespace-visible path.
2433    let socket_dir = tempfile::Builder::new()
2434        .prefix("hermit-sabre-rpc-")
2435        .tempdir_in(Path::new("/tmp"))?;
2436    let socket_path = socket_dir.path().join("coordinator.sock");
2437    let fallback_ready = Arc::new(AtomicBool::new(false));
2438    let global = Arc::new(detcore::GlobalState::init_global_state(&config).await);
2439    let server = reverie_rpc_transport::RpcServer::bind_with_readiness(
2440        &socket_path,
2441        global.clone(),
2442        config.clone(),
2443        fallback_ready.clone(),
2444    )
2445    .map_err(|error| anyhow!("failed to start SaBRe coordinator RPC: {error}"))?;
2446    let server_task = tokio::spawn(async move { server.serve().await });
2447
2448    // SaBRe runs with the guest's own argv and environment, so the kernel
2449    // builds the guest's initial stack, /proc/self/cmdline and
2450    // /proc/self/environ from them, as for an exec of the guest itself. The
2451    // plugin and image paths and the plugin's settings go in a sealed launch
2452    // specification instead (reverie_sabre_stats::launch), which SaBRe's loader
2453    // reads and closes before the guest starts. A script runs as its
2454    // interpreter, with the argv the kernel would give it.
2455    let mut first_bytes = vec![0u8; 256];
2456    let read = std::fs::File::open(launch_program)
2457        .and_then(|mut file| std::io::Read::read(&mut file, &mut first_bytes))
2458        .map_err(|error| {
2459            anyhow!(
2460                "failed to read SaBRe guest executable {}: {error}",
2461                launch_program.display()
2462            )
2463        })?;
2464    first_bytes.truncate(read);
2465    let arg0 = command.get_arg0().to_owned();
2466    let client = match reverie_sabre_stats::launch::shebang(&first_bytes) {
2467        Some((interpreter, argument)) => {
2468            command.program(&sabre);
2469            command.arg0(OsStr::from_bytes(&interpreter));
2470            let mut words: Vec<&OsStr> = argument
2471                .iter()
2472                .map(|word| OsStr::from_bytes(word))
2473                .collect();
2474            words.push(launch_program.as_os_str());
2475            command.prepend_args(words);
2476            PathBuf::from(OsStr::from_bytes(&interpreter))
2477        }
2478        None => {
2479            command.program(&sabre);
2480            command.arg0(&arg0);
2481            launch_program.to_path_buf()
2482        }
2483    };
2484    let mut launch_settings: Vec<Vec<u8>> = Vec::new();
2485    let mut setting = |name: &str, value: &OsStr| {
2486        let mut entry = name.as_bytes().to_vec();
2487        entry.push(b'=');
2488        entry.extend_from_slice(value.as_bytes());
2489        launch_settings.push(entry);
2490    };
2491    setting(SABRE_RPC_SOCKET_ENV, socket_path.as_os_str());
2492    command.env_remove(SABRE_RPC_SOCKET_ENV);
2493    command.env_remove(sabre_bootstrap::ENVIRONMENT);
2494    if bootstrap_launch.initializes_random() {
2495        setting(sabre_bootstrap::ENVIRONMENT, OsStr::new("1"));
2496    }
2497    // Publish the configuration and clock RPC fingerprint for this coordinator.
2498    // The plugin is a separate artifact in the same target directory, so it can
2499    // be stale without looking it. Its check before connecting names the mismatch
2500    // instead of failing to decode Config or a later DetTime request field.
2501    // See detcore_model::config_wire_fingerprint.
2502    setting(
2503        detcore::CONFIG_FINGERPRINT_ENV,
2504        OsStr::new(&detcore::config_wire_fingerprint()),
2505    );
2506    command.env_remove(detcore::CONFIG_FINGERPRINT_ENV);
2507    command.env_remove(SABRE_PATH_EVIDENCE_ENV);
2508    command.env_remove(SABRE_DETLOG_FORWARD_ENV);
2509    // Per emitting module, as each in-process `detlog!` callsite asks tracing:
2510    // asking only about `detcore` dropped every record a target-scoped
2511    // RUST_LOG (warn,detcore::random=info) keeps under ptrace.
2512    command.env_remove(SABRE_TOOL_OUTPUT_ENV);
2513    let detlog_policy = in_guest_detlog_forward_policy();
2514    // Kept open until the guest has started (it inherits its own copy).
2515    let mut _detlog_descriptor = None;
2516    if detlog_policy.forwards_any() {
2517        setting(
2518            SABRE_DETLOG_FORWARD_ENV,
2519            OsStr::new(&detlog_policy.encode()),
2520        );
2521        // With a socket (`hermit run --verify`), the plugin sends each record
2522        // on it from a descriptor reverie-sabre protects from the guest, and
2523        // the coordinator writes each thread's records into the log at that
2524        // thread's scheduler turns, as for in-guest LiteInst. Without one it
2525        // writes them to the guest's standard error.
2526        if let Some(socket) = inheritable_in_guest_detlog_socket()? {
2527            setting(
2528                SABRE_TOOL_OUTPUT_ENV,
2529                OsStr::new(&detcore::detlog::tool_output_env_value(socket.as_raw_fd())?),
2530            );
2531            _detlog_descriptor = Some(socket);
2532        }
2533    }
2534    command.env_remove("SABRE_BINARY");
2535    command.env_remove("SABRE_PLUGIN");
2536    // Always collect: the statistics page is a descriptor the guest can see,
2537    // so creating it only when a summary or DEBUG log is requested would make
2538    // those flags change the guest's view. Its number travels in the launch
2539    // specification, and the descriptor sits above the plugin's fixed RPC
2540    // socket.
2541    let stats = reverie_sabre_stats::SabreStats::create(reverie::BackendStatsRequest::ENABLED)
2542        .map_err(|error| anyhow!("failed to create the SaBRe statistics page: {error}"))?
2543        .expect("an enabled request creates the statistics page");
2544    setting(
2545        reverie_sabre_stats::BACKEND_STATS_ENV,
2546        OsStr::new(&stats.raw_fd().to_string()),
2547    );
2548    command.env_remove(reverie_sabre_stats::BACKEND_STATS_ENV);
2549    let launch_settings: Vec<&[u8]> = launch_settings.iter().map(Vec::as_slice).collect();
2550    let launch_spec = reverie_sabre_stats::launch::spec_bytes(
2551        plugin.as_os_str().as_bytes(),
2552        client.as_os_str().as_bytes(),
2553        &launch_settings,
2554    )
2555    .ok_or_else(|| anyhow!("the SaBRe launch specification is malformed or too large"))?;
2556    // Kept open until the guest has started (it inherits its own copy, which
2557    // SaBRe's loader closes).
2558    let _launch_spec = reverie_sabre_stats::launch::spec_fd(&launch_spec)
2559        .map_err(|error| anyhow!("failed to create the SaBRe launch specification: {error}"))?;
2560
2561    // THE SOCKET PATH IS DELIBERATELY RANDOM AND MUST NOT BE COMPARED.
2562    //
2563    // `tempfile` appends a random 6-character suffix to the directory above, so
2564    // the absolute path differs on every launch by design -- that is what keeps
2565    // concurrent hermit invocations on a shared host from binding the same
2566    // coordinator socket. Emitting it at INFO put per-launch randomness into the
2567    // INFO stream, which `--verify-strict` compares:
2568    //
2569    //   Mismatch at log messages 2 (run 1) and 2 (run 2):
2570    //   < socket=/tmp/hermit-sabre-rpc-Gw6tUi/coordinator.sock
2571    //   > socket=/tmp/hermit-sabre-rpc-7SZ94p/coordinator.sock
2572    //
2573    // That fails EVERY SaBRe verify cell before the guest executes an
2574    // instruction, for a host-side value with no guest-visible content. The
2575    // defect was in the oracle, not the backend.
2576    //
2577    // WHY THE VALUE IS DROPPED FROM INFO RATHER THAN MADE DETERMINISTIC: the two
2578    // `--verify` runs execute in SEPARATE CHILD PROCESSES, so any path stable
2579    // across both would have to be derived from state shared between them. That
2580    // trades `tempfile`'s guaranteed-fresh directory for a reused one, and a
2581    // run1 that dies holding the socket would then make run2 fail to bind -- a
2582    // real new failure mode in exchange for a cosmetic field. The path keeps its
2583    // randomness; only the compared stream stops carrying it.
2584    //
2585    // This is NOT a comparator relaxation. No normalization envelope is widened,
2586    // so any future randomness leaking into this banner still fails the
2587    // comparison. The full path remains available one level down.
2588    tracing::debug!(
2589        target: "hermit::sabre",
2590        socket = %socket_path.display(),
2591        "SaBRe coordinator RPC socket (per-launch temp path, deliberately not at INFO)",
2592    );
2593    tracing::info!(
2594        target: "hermit::sabre",
2595        guest = %program.display(),
2596        plugin = %plugin.display(),
2597        "launching Detcore guest through SaBRe with coordinator RPC",
2598    );
2599
2600    let supervised = match sabre_ptrace::run(
2601        command.into_std_lossy(),
2602        PathBuf::from(&sabre),
2603        plugin.clone(),
2604        fallback_ready,
2605        global.clone(),
2606        bootstrap_launch,
2607        stats.clone(),
2608        capture_output,
2609    )
2610    .await
2611    {
2612        Ok(supervised) => supervised,
2613        Err(error) => {
2614            global.release_all_physical_process_exits();
2615            global.force_shutdown_with_error();
2616            let _ = shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await;
2617            return Err(error);
2618        }
2619    };
2620    // The supervisor returns only after every tracee reached a final kernel wait status. Release
2621    // the root process's barrier (and any intentionally unreaped child barriers) before scheduler
2622    // shutdown; no guest thread remains that could race timer fast-forward here.
2623    global.release_all_physical_process_exits();
2624    // A SaBRe execution in which no guest thread ever reached the coordinator
2625    // is an execution in which Detcore was never loaded as a Reverie tool: the
2626    // guest ran on bare Linux. Treat it exactly like a failed run so the
2627    // scheduler is torn down here instead of blocking forever in `clean_up`
2628    // below, waiting for a guest thread that will never register.
2629    let detcore_never_engaged = !supervised.path_evidence.guest_rpc_observed;
2630    let requires_forced_shutdown = !supervised.status.success() || detcore_never_engaged;
2631    if requires_forced_shutdown {
2632        global.force_shutdown_with_error();
2633    }
2634    // Emit one unconditional, machine-readable per-run fact instead of a
2635    // free-form warning. SaBRe loads the guest interpreter before the Detcore
2636    // plugin, so pre-plugin loader syscalls are structurally absent from its
2637    // observation envelope. Versioning that fact lets scorecard consumers
2638    // reject old or incomplete records rather than infer coverage from silence.
2639    //
2640    // Keep this in the controller-diagnostic stream rather than writing
2641    // directly to the process stderr that also carries captured guest stderr.
2642    // WARN is Hermit's default tracing level, and `--log-file` can therefore
2643    // separate the unconditional controller fact from guest output without a
2644    // comparator exception. A missing record remains distinct from a record
2645    // whose counters are zero.
2646    let backend_evidence = sabre_backend_evidence_line(&supervised.path_evidence);
2647    tracing::warn!(target: "hermit::sabre", "{backend_evidence}");
2648    if let Some(path) = path_evidence_file {
2649        let mut file = fs::OpenOptions::new()
2650            .create(true)
2651            .append(true)
2652            .mode(0o600)
2653            .open(&path)
2654            .map_err(|error| {
2655                anyhow!(
2656                    "failed to open SaBRe path evidence {}: {error}",
2657                    path.display()
2658                )
2659            })?;
2660        serde_json::to_writer(&mut file, &supervised.path_evidence)?;
2661        writeln!(file)?;
2662    }
2663    let output = Output {
2664        status: supervised.status.into(),
2665        stdout: supervised.stdout,
2666        stderr: supervised.stderr,
2667    };
2668
2669    shutdown_sabre_rpc(server_task, &global, SABRE_RPC_DISCONNECT_TIMEOUT).await?;
2670    let mut global = Arc::try_unwrap(global).map_err(|global| {
2671        anyhow!(
2672            "SaBRe coordinator stopped with {} live RPC reference(s)",
2673            Arc::strong_count(&global) - 1
2674        )
2675    })?;
2676    if requires_forced_shutdown {
2677        global.cancel_internal_scheduler().await;
2678    }
2679    let dispatch_stats = backend_stats::report(
2680        Backend::Sabre,
2681        backend_stats::request(print_summary_to_json_file),
2682        &stats,
2683    );
2684    global
2685        .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
2686        .await;
2687    tracing::info!(
2688        target: "hermit::sabre::fallback",
2689        ptrace_fallback_sites = supervised.path_evidence.ptrace_fallback_sites,
2690        trusted_shared_object_sites = supervised.path_evidence.trusted_shared_object_sites,
2691        guest_rpc_observed = supervised.path_evidence.guest_rpc_observed,
2692        "SaBRe ptrace fallback completed",
2693    );
2694    if detcore_never_engaged {
2695        return Err(Error::new(BackendRunFailure)
2696            .context(sabre_uninstrumented_guest_message(&output.status)));
2697    }
2698    Ok(output)
2699}
2700
2701#[cfg(not(feature = "sabre"))]
2702async fn run_sabre(
2703    _command: Command,
2704    _config: DetConfig,
2705    _print_summary: bool,
2706    _print_summary_to_json_file: &Option<PathBuf>,
2707    _capture_output: bool,
2708) -> Result<Output, Error> {
2709    Backend::Sabre.ensure_available()?;
2710    unreachable!("SaBRe availability must fail when the feature is disabled");
2711}
2712
2713/// Classify the existing SaBRe reach evidence without collapsing "never
2714/// engaged" into the same zero-valued state as a fully exercised run.
2715#[cfg(feature = "sabre")]
2716fn sabre_reach_state(guest_rpc_observed: bool, ptrace_fallback_sites: usize) -> &'static str {
2717    match (guest_rpc_observed, ptrace_fallback_sites) {
2718        (false, _) => "no-detcore-reached",
2719        (true, 1..) => "degraded-ptrace-fallback",
2720        (true, 0) => "sabre-exercised",
2721    }
2722}
2723
2724/// Produce the versioned SaBRe backend fact consumed by compatibility reports.
2725///
2726/// `preplugin_coverage=absent` is a property of SaBRe's launch order: the guest
2727/// interpreter runs before the Detcore plugin is loaded. It is recorded rather
2728/// than inferred from counters because the ptrace fallback cannot observe that
2729/// interval either.
2730///
2731/// Preserve the originating #1725 measurement as provenance for that field:
2732/// on its measurement host, `/bin/true` produced 3 COMMITs under SaBRe versus
2733/// 14 under ptrace; the 11 absent records were the loader's libc.so.6 path
2734/// resolution. The launch-order fact, not that host-specific count, is the
2735/// runtime contract.
2736#[cfg(feature = "sabre")]
2737fn sabre_backend_evidence_line(evidence: &sabre_ptrace::PathEvidence) -> String {
2738    format!(
2739        ":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
2740         evidence_schema={}; preplugin_coverage=absent; ptrace_fallback_sites={}; \
2741         trusted_shared_object_sites={}; guest_rpc_observed={}; reach_state={}",
2742        evidence.schema,
2743        evidence.ptrace_fallback_sites,
2744        evidence.trusted_shared_object_sites,
2745        evidence.guest_rpc_observed,
2746        sabre_reach_state(evidence.guest_rpc_observed, evidence.ptrace_fallback_sites),
2747    )
2748}
2749
2750/// Explain a SaBRe run whose guest never reached the Detcore coordinator.
2751///
2752/// `guest_rpc_observed` is set by the coordinator RPC listener the first time a
2753/// SaBRe-loaded guest connects. When it stays false the guest completed without
2754/// Detcore intercepting anything, so the run carries no determinism guarantee
2755/// whatsoever -- its timing, scheduling, PIDs, and clock reads all came from the
2756/// host. Reporting that as a successful `hermit run` would be a fail-open
2757/// determinism hole, so the caller turns it into a hard error and this function
2758/// supplies the diagnosis.
2759///
2760/// The dominant cause is a guest whose syscall sites SaBRe never rewrote. A
2761/// statically linked ELF is the sharp edge: it has no dynamic loader and no
2762/// shared library through which SaBRe could regain control, so an unrewritten
2763/// static client runs entirely on bare Linux with no second chance.
2764#[cfg(feature = "sabre")]
2765fn sabre_uninstrumented_guest_message(status: &ExitStatus) -> String {
2766    format!(
2767        "the SaBRe backend finished ({status:?}) without the guest ever reaching the Detcore \
2768         coordinator: no syscall was intercepted, so this run applied no determinization at all \
2769         and its result is not a Hermit guarantee. This means SaBRe rewrote no syscall site in \
2770         the guest -- most often a statically linked ELF, whose syscall sites SaBRe must patch \
2771         in the client image itself because there is no dynamic loader to intercept."
2772    )
2773}
2774
2775/// Guest-physical memory available to the single-process KVM personality.
2776// The KVM personality is a sparse MAP_NORESERVE address space. QEMU needs room
2777// for its own ELF mappings in addition to the nested machine's RAM mapping.
2778// reverie-kvm places every guest mapping in this window, even a PROT_NONE
2779// reservation, so a runtime that reserves address space up front needs room
2780// here: node's V8 reserves 256, 128 and then 512 MiB twice, which 1 GiB could
2781// not hold (https://github.com/rrnewton/hermit/issues/4366). 3 GiB is the
2782// largest window reverie-kvm's bootstrap identity-maps. The window costs the
2783// host only the pages a guest touches, and mmap and munmap discard ranges of
2784// 2 MiB or more rather than writing zeros over them
2785// (https://github.com/rrnewton/reverie/pull/1059). madvise(MADV_DONTNEED)
2786// still writes zeros over every page, and node calls it over its 512 MiB
2787// reservation, so a node run peaks near 880 MB of host memory until that is
2788// made lazy too (https://github.com/rrnewton/hermit/issues/4366).
2789const KVM_GUEST_MEMORY_BYTES: usize = 3 * 1024 * 1024 * 1024;
2790
2791/// Maximum `#!` interpreter indirection levels, matching the Linux kernel's
2792/// `BINPRM_MAX_RECURSION` limit for chained script interpreters.
2793const MAX_SHEBANG_DEPTH: usize = 4;
2794
2795/// Resolve `#!` interpreter scripts before the reverie-kvm ELF loader runs.
2796///
2797/// The KVM ELF loader can only map ELF images, so a guest program that is
2798/// actually a `#!`-script (for example `/usr/local/bin/file` -> `#!/bin/bash`,
2799/// or `/usr/bin/pkg-config` -> `#!/usr/bin/sh`) must be rewritten to launch its
2800/// interpreter, exactly as the kernel's `execve(2)` `binfmt_script` handler
2801/// does. On success the returned image is an ELF and `argv` has the interpreter,
2802/// its shebang arguments, and the script path prepended in kernel order:
2803/// `[interp, shebang_args.., script_path, <original argv[1..]>]`.
2804///
2805/// The interpreter line is parsed with hermit's shared [`Shebang`] so the KVM
2806/// backend matches how the ptrace backend and recorder treat `#!`-scripts.
2807fn resolve_kvm_shebang(
2808    resolved_program: &Path,
2809    mut argv: Vec<String>,
2810) -> Result<(PathBuf, Vec<String>, Vec<u8>), Error> {
2811    let mut load_path = resolved_program.to_path_buf();
2812    let mut image = fs::read(&load_path)
2813        .map_err(|error| anyhow!("failed to read KVM guest executable {load_path:?}: {error}"))?;
2814
2815    let mut depth = 0;
2816    while image.starts_with(b"#!") {
2817        depth += 1;
2818        if depth > MAX_SHEBANG_DEPTH {
2819            return Err(anyhow!(
2820                "too many levels of `#!` interpreter indirection loading {resolved_program:?}"
2821            ));
2822        }
2823        let (interpreter, shebang_args) = Shebang::from_buf(&image)
2824            .ok_or_else(|| anyhow!("malformed `#!` interpreter line in {load_path:?}"))?
2825            .into_parts();
2826        let interpreter_str = interpreter
2827            .to_str()
2828            .ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter path in {load_path:?}"))?
2829            .to_owned();
2830
2831        // Rewrite argv in kernel order. The prior argv[0] (the script's own
2832        // name) is dropped on the first level; on deeper levels the previous
2833        // interpreter path is preserved as a positional argument, matching
2834        // `binfmt_script`.
2835        let mut rewritten = Vec::with_capacity(argv.len() + shebang_args.len() + 2);
2836        rewritten.push(interpreter_str);
2837        for arg in &shebang_args {
2838            rewritten.push(
2839                arg.to_str()
2840                    .ok_or_else(|| anyhow!("non-UTF-8 `#!` interpreter argument in {load_path:?}"))?
2841                    .to_owned(),
2842            );
2843        }
2844        rewritten.push(load_path.to_string_lossy().into_owned());
2845        rewritten.extend_from_slice(&argv[1..]);
2846        argv = rewritten;
2847
2848        load_path = interpreter;
2849        image = fs::read(&load_path).map_err(|error| {
2850            anyhow!(
2851                "failed to read `#!` interpreter {load_path:?} for {resolved_program:?}: {error}"
2852            )
2853        })?;
2854    }
2855
2856    Ok((load_path, argv, image))
2857}
2858
2859/// The container replaces this host directory with a private, empty tmpfs, so
2860/// nothing beneath it is visible to the guest. Kept next to the diagnostic that
2861/// depends on it; `run.rs` has its own `TMP_DIR` for the mount itself.
2862const CONTAINER_REPLACED_TMP: &str = "/tmp";
2863
2864/// Explain why a working directory that plainly exists on the host could not be
2865/// resolved for the guest.
2866///
2867/// ⚠️ THIS FUNCTION EXISTS BECAUSE THE BARE ERROR CAUSED A MISDIAGNOSIS, not to
2868/// be tidy. `fs::canonicalize` runs after the container's mounts are applied, and
2869/// the container bind-mounts a fresh empty tmpfs over `/tmp`
2870/// (`bin/hermit/container.rs`). So a cwd beneath `/tmp` is genuinely absent from
2871/// the guest's mount namespace and `canonicalize` returns a perfectly correct
2872/// `NotFound` -- for a directory the user can `ls`.
2873///
2874/// Reported 2026-08-25 as "run_kvm_ cli tests fail from a git worktree". They do
2875/// not. Measured across five working directories with one binary: a PLAIN
2876/// directory under `/tmp` with no git in it FAILS, and a linked git worktree
2877/// under `/home` WORKS. The only property that tracks the failure is "the cwd is
2878/// under /tmp"; `/tmp` itself resolves because the mount POINT exists. The git
2879/// hypothesis cost real investigation time, and it came from this message saying
2880/// only "No such file or directory".
2881///
2882/// It mattered more than a stray report because the historical landing recipe
2883/// placed detached worktrees below `/tmp`, exactly where this fires. Current
2884/// dev-hermit worktrees are created through wrkslots below `worktrees/`, but the
2885/// diagnostic remains necessary for arbitrary callers and older checkouts.
2886///
2887/// The message names the mechanism and both ways out. It deliberately does NOT
2888/// silently fall back to `/`: changing the guest's working directory out from
2889/// under a caller who asked for a specific one would trade a loud, correct
2890/// failure for a quiet, wrong success.
2891fn kvm_cwd_resolution_error(requested_cwd: &Path, error: &std::io::Error) -> Error {
2892    let under_replaced_tmp = requested_cwd.starts_with(CONTAINER_REPLACED_TMP)
2893        && requested_cwd != Path::new(CONTAINER_REPLACED_TMP);
2894    if error.kind() == std::io::ErrorKind::NotFound && under_replaced_tmp {
2895        anyhow!(
2896            "failed to resolve KVM guest working directory {:?}: {error}\n\
2897             \n\
2898             This directory may well exist on the host. The container replaces \
2899             {CONTAINER_REPLACED_TMP} with a private, empty tmpfs, so nothing beneath \
2900             {CONTAINER_REPLACED_TMP} is visible to the guest, and resolving the working \
2901             directory happens inside that mount namespace.\n\
2902             Either run from a directory outside {CONTAINER_REPLACED_TMP}, or pass \
2903             --workdir with a path that exists inside the guest.",
2904            requested_cwd
2905        )
2906    } else {
2907        anyhow!(
2908            "failed to resolve KVM guest working directory {:?}: {error}",
2909            requested_cwd
2910        )
2911    }
2912}
2913
2914/// Bind KVM's raw mountinfo and fdinfo to the same filesystem namespace.
2915///
2916/// The CLI supplies IdentityGuard provenance from the completed container: the
2917/// namespace's row/parent order and the namespace it was captured in
2918/// ([`detcore_model::config::MountNamespaceIdentity`], whose kernel ID Linux
2919/// never reuses during a boot). The backend requires its own mount namespace
2920/// to be that one and keeps the producer's order, the same snapshot the
2921/// container mount table was built from; it does not take a second one, and
2922/// it refuses provenance that is not well formed (a duplicate ID, an empty
2923/// order, an assignment Detcore's pool would refuse, a root rewrite or table
2924/// row outside the order).
2925///
2926/// Two captures of one private namespace need not agree. When a host process
2927/// removes the directory a host mount was on, Linux detaches the mounts on that
2928/// dentry in every mount namespace (`vfs_rmdir`, `vfs_unlink` and rename call
2929/// `detach_mounts`, and `__detach_mounts` in fs/namespace.c unmounts each
2930/// mount on the dentry with `umount_tree`), so a copied host row can leave the
2931/// container between two reads although nothing propagates into it. The
2932/// snapshot keeps naming that row. A detached mount stays usable through what
2933/// still holds it (an open descriptor, a working directory, a directory
2934/// descriptor), and fdinfo `mnt_id` and STATX_MNT_ID still number it through
2935/// the order; later mountinfo views lack it and stay ordered subsets of the
2936/// snapshot, which Detcore's validation accepts. A kernel automount (an autofs
2937/// trigger reached by an ordinary path lookup) can add a row after the
2938/// snapshot despite the private propagation: fdinfo and statx number its new
2939/// ID on first observation, and a later kernel-view mountinfo that shows it is
2940/// not an ordered subset and is refused. The container mount table never shows
2941/// it.
2942/// A library caller that built no container and supplies no provenance gets
2943/// this capture; `--no-namespace` runs supply it from Hermit's own namespace
2944/// (`complete_container_config`). Either way Detcore renders the guest's mount
2945/// files from the container mount table. KVM does not permit guest namespace
2946/// changes.
2947fn prepare_kvm_mountinfo_config(
2948    config: &mut DetConfig,
2949    namespace: impl FnOnce() -> Result<detcore_model::config::MountNamespaceIdentity, Error>,
2950    capture: impl FnOnce() -> Result<Vec<u64>, Error>,
2951) -> Result<(), Error> {
2952    if !config.mountinfo_mount_ids_captured
2953        && (!config.mountinfo_mount_ids.is_empty()
2954            || !config.mount_id_assignment_order.is_empty()
2955            || config.mountinfo_mount_namespace.is_some())
2956    {
2957        anyhow::bail!("KVM mount identities have no producer-captured namespace");
2958    }
2959    if config.mountinfo_mount_ids_captured {
2960        let Some(producer) = config.mountinfo_mount_namespace else {
2961            anyhow::bail!(
2962                "KVM producer-captured mount identities do not name their mount namespace"
2963            );
2964        };
2965        // Every mount namespace has its root, so a real one never yields an
2966        // empty order; and Detcore's pool refuses a malformed one.
2967        if config.mountinfo_mount_ids.is_empty()
2968            || !detcore_model::procfs::mount_identity_provenance_is_well_formed(
2969                &config.mountinfo_mount_ids,
2970                &config.mount_id_assignment_order,
2971            )
2972        {
2973            anyhow::bail!(
2974                "KVM producer-captured mount identities are malformed ({} listed, {} assigned)",
2975                config.mountinfo_mount_ids.len(),
2976                config.mount_id_assignment_order.len()
2977            );
2978        }
2979        if let Some(missing) = config
2980            .mountinfo_root_rewrites
2981            .iter()
2982            .map(|rewrite| rewrite.raw_mount_id)
2983            .find(|id| !config.mountinfo_mount_ids.contains(id))
2984        {
2985            anyhow::bail!(
2986                "KVM mount root rewrite names mount {missing}, which the producer's snapshot does \
2987                 not have"
2988            );
2989        }
2990        let backend = namespace().context("failed to identify the KVM backend mount namespace")?;
2991        if producer != backend {
2992            anyhow::bail!(
2993                "KVM producer-captured mount identities name another mount namespace \
2994                 (captured in {producer:?}, backend in {backend:?})"
2995            );
2996        }
2997    } else {
2998        let order = capture().context("failed to capture the KVM backend mount namespace")?;
2999        config.mountinfo_mount_ids = order;
3000        config.mountinfo_mount_ids_captured = true;
3001    }
3002    // The container mount table Detcore renders on KVM too names mounts of
3003    // this same namespace: refuse one built in another.
3004    if let Some(table) = &config.container_mount_table
3005        && let Some(missing) = table
3006            .mounts
3007            .iter()
3008            .map(|row| row.raw_mount_id)
3009            .find(|id| !config.mountinfo_mount_ids.contains(id))
3010    {
3011        anyhow::bail!(
3012            "KVM container mount table names mount {missing}, which the backend namespace does \
3013             not have"
3014        );
3015    }
3016    // The backend now exposes the actual namespace's devices. There is no
3017    // synthetic 0:1 root device to translate; stat and mountinfo use the same
3018    // raw identities before entering Detcore's shared DevicePool.
3019    config.mountinfo_device_rewrites.clear();
3020    Ok(())
3021}
3022
3023// AUTONOMOUS-BOT-IMPLEMENTED
3024// TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/issues/3695): Review
3025// host metadata timestamps for KVM runs.
3026/// Whether a KVM run asks the backend for the timestamps the kernel stored
3027/// rather than its fixed value.
3028///
3029/// With virtual metadata, Detcore rewrites every timestamp that a stat call
3030/// returns to the guest, and it reads the stored host values for its own
3031/// checks: `set_file_times` confirms that `utimensat` stored the requested
3032/// mtime. KVM replaces those timestamps with a fixed value unless the run asks
3033/// for the stored ones. The backend refuses this setting unless Detcore owns
3034/// every guest thread, which `run_kvm` never opts out of. The stored values sit
3035/// in the guest's buffer until Detcore rewrites them, so the run must also
3036/// sequentialize threads: then no other guest thread runs in that interval.
3037fn kvm_reports_stored_metadata_timestamps(config: &DetConfig) -> bool {
3038    config.virtualize_metadata && config.sequentialize_threads
3039}
3040
3041/// Dispatch a command onto the real reverie-kvm Tool runtime.
3042async fn run_kvm(
3043    command: &Command,
3044    mut config: DetConfig,
3045    print_summary: bool,
3046    print_summary_to_json_file: &Option<PathBuf>,
3047    capture_output: bool,
3048) -> Result<Output, Error> {
3049    let dispatch_started = Instant::now();
3050    // A caller that built no container (a library caller): the KVM guest's
3051    // host file operations run in this process's namespace, whatever its
3052    // command asks (the backend applies no chroot or mount of the command),
3053    // so its table is this namespace's. A caller with no provenance at all
3054    // takes the order from the same read; malformed provenance is still
3055    // refused below.
3056    if config.container_mount_table.is_none() {
3057        let launch_cwd = command
3058            .get_current_dir()
3059            .map_or_else(|| Path::new(".").to_owned(), Path::to_owned);
3060        let (table, order) = unplanned_container_mount_table(&launch_cwd)?;
3061        if !config.mountinfo_mount_ids_captured
3062            && config.mountinfo_mount_ids.is_empty()
3063            && config.mount_id_assignment_order.is_empty()
3064            && config.mountinfo_mount_namespace.is_none()
3065        {
3066            config.mountinfo_mount_namespace = Some(current_mount_namespace()?);
3067            config.mountinfo_mount_ids = order;
3068            config.mountinfo_mount_ids_captured = true;
3069        }
3070        config.container_mount_table = Some(table);
3071    }
3072    let keep = config
3073        .container_mount_table
3074        .as_ref()
3075        .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
3076        .unwrap_or_default();
3077    prepare_kvm_mountinfo_config(&mut config, current_mount_namespace, || {
3078        capture_mountinfo_identity_order_keeping(&keep)
3079    })?;
3080    let stdin = if capture_output {
3081        let (snapshot_reserved, snapshot) = output_backend_stdin_reservation()?;
3082        if snapshot_reserved {
3083            snapshot
3084        } else {
3085            // Public KVM output-capture callers do not pass through the CLI's
3086            // verify setup. Preserve their existing stdin behavior instead of
3087            // silently replacing it with /dev/null merely because output is
3088            // captured.
3089            reserved_kvm_stdin()?
3090        }
3091    } else {
3092        reserved_kvm_stdin()?
3093    };
3094    let requested_cwd = command
3095        .get_current_dir()
3096        .map(Path::to_owned)
3097        .unwrap_or(std::env::current_dir()?);
3098    let cwd = fs::canonicalize(&requested_cwd)
3099        .map_err(|error| kvm_cwd_resolution_error(&requested_cwd, &error))?;
3100    let program = command
3101        .get_program()
3102        .to_str()
3103        .ok_or_else(|| anyhow!("KVM guest executable path is not valid UTF-8"))?
3104        .to_owned();
3105    if !cwd.is_dir() {
3106        return Err(anyhow!(
3107            "KVM guest working directory is not a directory: {:?}",
3108            cwd
3109        ));
3110    }
3111    let resolved_program = command.find_program().map_err(|error| {
3112        anyhow!("failed to resolve KVM guest executable {program:?} in the guest PATH: {error}")
3113    })?;
3114    let mut argv = Vec::with_capacity(1 + command.get_args().count());
3115    argv.push(program.clone());
3116    for argument in command.get_args() {
3117        argv.push(
3118            argument
3119                .to_str()
3120                .ok_or_else(|| anyhow!("KVM guest argument is not valid UTF-8"))?
3121                .to_owned(),
3122        );
3123    }
3124
3125    // Rewrite `#!`-scripts to their interpreter before the ELF loader sees them.
3126    let (_interpreter_path, argv, image) = resolve_kvm_shebang(&resolved_program, argv)?;
3127    // After shebang resolution the executable is the interpreter (argv[0]).
3128    let program = argv.first().cloned().unwrap_or(program);
3129    let envp = command
3130        .get_captured_envs()
3131        .into_iter()
3132        .map(|(key, value)| {
3133            let key = key
3134                .to_str()
3135                .ok_or_else(|| anyhow!("KVM guest environment key is not valid UTF-8"))?;
3136            let value = value
3137                .to_str()
3138                .ok_or_else(|| anyhow!("KVM guest environment value is not valid UTF-8"))?;
3139            Ok(format!("{key}={value}"))
3140        })
3141        .collect::<Result<Vec<_>, Error>>()?;
3142    tracing::info!(
3143        target: "hermit::kvm",
3144        program = %program,
3145        argv = ?argv,
3146        cwd = %cwd.display(),
3147        env_count = envp.len(),
3148        "launching guest through reverie-kvm",
3149    );
3150    let argv = argv.iter().map(String::as_str).collect::<Vec<_>>();
3151    let envp = envp.iter().map(String::as_str).collect::<Vec<_>>();
3152
3153    let setup_started = Instant::now();
3154    // `prepare_backend_config` already copied `KvmBackend::capabilities()`,
3155    // which reports the backend's own CPUID table and that, of the madvise
3156    // advice with guest-visible semantics, it implements only MADV_DONTNEED.
3157    // KVM does not enter Hermit's UTS namespace, so Detcore must provide the
3158    // same synthetic identity that the namespace-backed ptrace path exposes.
3159    // TODO-HUMAN-REVIEW(PR-998): Review KVM UTS namespace parity.
3160    config.has_uts_namespace = false;
3161    let random_seed = config.rng_seed();
3162    let mut backend = reverie_kvm::KvmBackend::new_with_stdin(KVM_GUEST_MEMORY_BYTES, stdin)
3163        .map_err(|error| anyhow!("failed to initialize reverie-kvm: {error}"))?;
3164    // AUTONOMOUS-BOT-IMPLEMENTED
3165    // TODO-HUMAN-REVIEW(PR-1120): Review KVM's canonical Detcore root identity.
3166    backend
3167        .set_root_pid(detcore::ROOT_DETPID.as_raw())
3168        .map_err(|error| anyhow!("failed to configure KVM root PID: {error}"))?;
3169    // Guests see their task IDs, so number them as the ptrace reference does
3170    // (one extra ID per task for its tracer thread; see reverie::task_ids).
3171    backend
3172        .set_ids_per_task(reverie::task_ids::HERMIT_PTRACE_IDS_PER_TASK)
3173        .map_err(|error| anyhow!("failed to configure KVM task IDs: {error}"))?;
3174    // The ptrace launcher execs the path `find_program` resolved, so that is
3175    // the filename Linux records in AT_EXECFN and copies to the top of the
3176    // stack, including for a `#!` script whose argv now starts with the
3177    // interpreter.
3178    backend
3179        .install_static_elf_with_exec_context(
3180            &image,
3181            resolved_program.as_os_str(),
3182            &argv,
3183            &envp,
3184            &cwd,
3185        )
3186        .map_err(|error| anyhow!("failed to load KVM guest executable {program:?}: {error}"))?;
3187    // The loader has copied the image's segments into guest memory, so the
3188    // file's bytes are no longer needed. Holding them until the run ends kept
3189    // a second copy of the program in host memory for the whole run: 75 MB
3190    // for node (https://github.com/rrnewton/reverie/issues/1063).
3191    drop(image);
3192    backend
3193        .set_random_seed(random_seed)
3194        .map_err(|error| anyhow!("failed to configure KVM guest random seed: {error}"))?;
3195    // The KVM backend defaults to Tool-owned guest threads: CLONE_THREAD
3196    // workers are driven through the Detcore tool loop and their futex/CLEARTID
3197    // synchronization routes to Detcore, matching the golden ptrace model
3198    // ("follow children"). Detcore registers every cloned thread as a tool
3199    // thread (detcore/src/syscalls/threads.rs), so the backend must stay in
3200    // that mode: host-owned threads would split worker execution and futex
3201    // ownership across two synchronization domains, which deadlocks
3202    // pthread_join.
3203    if kvm_reports_stored_metadata_timestamps(&config) {
3204        backend
3205            .set_host_metadata_timestamps(true)
3206            .map_err(|error| anyhow!("failed to configure KVM metadata timestamps: {error}"))?;
3207    }
3208
3209    let execution_started = Instant::now();
3210    let completion = hermit_run_kvm::run_detcore(&mut backend, config, capture_output)
3211        .await
3212        .map_err(|error| kvm_execution_error(error, None))?;
3213    let cleanup_started = Instant::now();
3214    let result =
3215        finish_kvm_tool_completion(completion, print_summary, print_summary_to_json_file).await;
3216    let teardown_started = Instant::now();
3217    // Drop explicitly so the host's KVM VM teardown cost remains observable.
3218    drop(backend);
3219    let teardown_finished = Instant::now();
3220    let (status, stdout, stderr) = result?;
3221
3222    // Every field below is a host wall-clock duration. Keep this diagnostic at
3223    // DEBUG so it remains available for backend profiling without entering the
3224    // INFO stream exposed to canonical comparison. KVM's built-in verification
3225    // is still output/status-only; this classification does not claim KVM L2.
3226    tracing::debug!(
3227        target: "hermit::kvm",
3228        prepare_us = setup_started.duration_since(dispatch_started).as_micros() as u64,
3229        setup_us = execution_started.duration_since(setup_started).as_micros() as u64,
3230        execution_us = cleanup_started.duration_since(execution_started).as_micros() as u64,
3231        cleanup_us = teardown_started.duration_since(cleanup_started).as_micros() as u64,
3232        teardown_us = teardown_finished.duration_since(teardown_started).as_micros() as u64,
3233        lifecycle_us = teardown_finished.duration_since(dispatch_started).as_micros() as u64,
3234        "reverie-kvm lifecycle phase timings",
3235    );
3236
3237    if !capture_output {
3238        std::io::stdout().write_all(&stdout)?;
3239        std::io::stderr().write_all(&stderr)?;
3240    }
3241
3242    Ok(Output {
3243        status,
3244        stdout,
3245        stderr,
3246    })
3247}
3248
3249// A runtime error still owns GlobalState. Finish its terminal daemon before
3250// returning the typed cause to the CLI's error classifier.
3251async fn finish_kvm_tool_completion(
3252    completion: reverie_kvm::ToolRunCompletion<detcore::GlobalState>,
3253    print_summary: bool,
3254    print_summary_to_json_file: &Option<PathBuf>,
3255) -> Result<(ExitStatus, Vec<u8>, Vec<u8>), Error> {
3256    match completion.result {
3257        Ok(output) => {
3258            completion
3259                .global_state
3260                .clean_up(print_summary, print_summary_to_json_file)
3261                .await;
3262            Ok(output)
3263        }
3264        Err(error) => {
3265            let cleanup = completion
3266                .global_state
3267                .clean_up_after_backend_failure()
3268                .await;
3269            Err(kvm_execution_error(error, Some(cleanup)))
3270        }
3271    }
3272}
3273
3274fn kvm_execution_error(
3275    primary: reverie_kvm::Error,
3276    cleanup: Option<detcore::BackendFailureCleanup>,
3277) -> Error {
3278    // The manifest runner retains the first Error line. Keep the cause there,
3279    // as well as the typed backend and optional scheduler errors in the chain.
3280    let message = format!("KVM guest execution failed: {primary}");
3281    let mut error = Error::new(primary).context(BackendRunFailure);
3282    if let Some(cleanup) = cleanup {
3283        if let Err(recording) = cleanup.preemption_recording {
3284            error = error.context(format!("partial preemption recording failed: {recording}"));
3285        }
3286        if let Err(scheduler) = cleanup.scheduler {
3287            error = error.context(scheduler);
3288        }
3289    }
3290    error.context(message)
3291}
3292
3293#[cfg(test)]
3294mod kvm_failure_tests;
3295
3296#[cfg(all(test, feature = "kvm-execution-tests"))]
3297mod kvm_execution_tests;
3298
3299// TODO-HUMAN-REVIEW(PR-743): Review bounded relaunch before DBT guest execution.
3300#[cfg(feature = "dbt")]
3301fn dbt_client_thread_start_failed(status: &std::process::ExitStatus) -> bool {
3302    status.code() == Some(reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE)
3303}
3304
3305/// Keys that `HERMIT_DBT_DETCONFIG` still carries although [`DetConfig`] no
3306/// longer has the switches they named. Each entry is the key, its fixed value,
3307/// and the key it preceded in the old field order.
3308///
3309/// These are serialization constants. Nothing reads them back: the admitted
3310/// DBT standalone path decodes the variable with
3311/// [`detcore::decode_backend_config_json`], whose legacy reader ignores these
3312/// keys. The values are the only ones the deleted switches ever took on any
3313/// backend.
3314const LEGACY_DBT_DETCONFIG_KEYS: [(&str, bool, &str); 3] = [
3315    (
3316        "use_thread_local_clock_reads",
3317        false,
3318        "detect_host_clock_futex_timeouts",
3319    ),
3320    (
3321        "backend_serializes_fork_children",
3322        false,
3323        "backend_tracks_process_children",
3324    ),
3325    (
3326        "backend_dispatches_thread_tools",
3327        true,
3328        "backend_tracks_process_children",
3329    ),
3330];
3331
3332/// Serialize `config` for the DBT runtime's `HERMIT_DBT_DETCONFIG` variable.
3333///
3334/// This is not plain `serde_json::to_string` because the variable sits in the
3335/// guest's own environment. A guest can read it through `getenv`, `printenv`
3336/// or `/proc/self/environ`, so its bytes are guest-visible. Two later changes
3337/// to [`DetConfig`] would otherwise have changed what every DBT guest
3338/// observes, and each is undone here:
3339///
3340/// - The backend facts moved into [`DetConfig::backend`].
3341///   [`detcore::to_legacy_backend_json`] writes them back out as the fifteen
3342///   separate keys they were, at the position the object carried them.
3343/// - Three always-constant switches were deleted, which would have shortened
3344///   the variable by 117 bytes. The keys in `LEGACY_DBT_DETCONFIG_KEYS` are
3345///   re-inserted at their old positions.
3346///
3347/// When the legacy keys express every backend capability exactly, the output
3348/// is byte-identical to what the same config produced before either change.
3349/// That is pinned by golden bytes in the tests below. Otherwise a versioned
3350/// envelope carries the exact capabilities alongside the legacy config.
3351///
3352/// Coordinated DBT startup receives the authoritative typed Config through the
3353/// RPC handshake. This JSON remains guest-visible and supplies the admitted
3354/// standalone fallback, so its representable bytes still need preservation.
3355/// Remove this shim only when that variable no longer reaches the guest.
3356#[doc(hidden)]
3357pub fn dbt_detconfig_json(config: &DetConfig) -> serde_json::Result<String> {
3358    let legacy = insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(config)?)?;
3359    detcore::encode_backend_config_json(legacy, config.backend)
3360}
3361
3362/// Re-insert [`LEGACY_DBT_DETCONFIG_KEYS`] into a serialized [`DetConfig`].
3363///
3364/// The insertion works on the parsed top-level object, never on substrings,
3365/// so string values that happen to contain a key name cannot move it. It
3366/// refuses, rather than guessing, when an anchor key is missing or repeated or
3367/// when a legacy key is already present.
3368fn insert_legacy_dbt_detconfig_keys(serialized: &str) -> serde_json::Result<String> {
3369    use serde::de::MapAccess;
3370    use serde::ser::Error as _;
3371    use serde::ser::SerializeMap;
3372    use serde_json::value::RawValue;
3373
3374    /// The top-level members of a JSON object in document order, each value
3375    /// kept as its exact serialized bytes.
3376    struct Members<'a>(Vec<(&'a str, &'a RawValue)>);
3377
3378    impl<'de> serde::Deserialize<'de> for Members<'de> {
3379        fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
3380            struct MembersVisitor;
3381            impl<'de> serde::de::Visitor<'de> for MembersVisitor {
3382                type Value = Members<'de>;
3383                fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
3384                    formatter.write_str("a serialized Detcore config object")
3385                }
3386                fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
3387                    let mut members = Vec::new();
3388                    while let Some(member) = map.next_entry()? {
3389                        members.push(member);
3390                    }
3391                    Ok(Members(members))
3392                }
3393            }
3394            deserializer.deserialize_map(MembersVisitor)
3395        }
3396    }
3397
3398    impl serde::Serialize for Members<'_> {
3399        fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
3400            let mut map = serializer.serialize_map(None)?;
3401            for (key, value) in &self.0 {
3402                for (legacy_key, fixed_value, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
3403                    if anchor == *key {
3404                        map.serialize_entry(legacy_key, &fixed_value)?;
3405                    }
3406                }
3407                map.serialize_entry(key, value)?;
3408            }
3409            map.end()
3410        }
3411    }
3412
3413    let members: Members<'_> = serde_json::from_str(serialized)?;
3414    for (legacy_key, _, anchor) in LEGACY_DBT_DETCONFIG_KEYS {
3415        let anchors = members.0.iter().filter(|(key, _)| *key == anchor).count();
3416        if anchors != 1 {
3417            return Err(serde_json::Error::custom(format!(
3418                "cannot place legacy DBT config key {legacy_key:?}: its anchor key {anchor:?} \
3419                 appears {anchors} times, expected exactly once"
3420            )));
3421        }
3422        if members.0.iter().any(|(key, _)| *key == legacy_key) {
3423            return Err(serde_json::Error::custom(format!(
3424                "legacy DBT config key {legacy_key:?} is already present; it must come only \
3425                 from the fixed legacy table"
3426            )));
3427        }
3428    }
3429    serde_json::to_string(&members)
3430}
3431
3432#[cfg(test)]
3433mod dbt_detconfig_tests {
3434    use std::path::PathBuf;
3435
3436    use clap::Parser;
3437    use detcore_model::config::MountInfoRootRewrite;
3438
3439    use super::Backend;
3440    use super::DetConfig;
3441    use super::dbt_detconfig_json;
3442    use super::insert_legacy_dbt_detconfig_keys;
3443    use super::prepare_backend_config;
3444
3445    /// `HERMIT_DBT_DETCONFIG` bytes for each config below, captured with
3446    /// `serde_json::to_string` from a build of
3447    /// 806cf2fa38d13b806195d54aeba22d282d79f33d, which still had the legacy
3448    /// switches. Any later change to `DetConfig`'s serialized fields also
3449    /// changes this guest-visible variable, so this test is meant to fail on
3450    /// it and make that change a deliberate one.
3451    ///
3452    /// Two deliberate changes since that capture: the empty
3453    /// `fdinfo_unlisted_mount_ids` key was renamed `mount_id_assignment_order`
3454    /// when Detcore began numbering mount IDs in first-observation order
3455    /// (RECORD_VERSION 0x122), and the `proc_level` key was added by the
3456    /// `/proc` levels (https://github.com/rrnewton/hermit/issues/4266), whose
3457    /// default is `Minimal`. Every other byte is the 806cf2fa output.
3458    const GOLDEN: [(&str, &str); 3] = [
3459        (
3460            "default",
3461            include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-default.json"),
3462        ),
3463        (
3464            "dbt",
3465            include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-dbt.json"),
3466        ),
3467        (
3468            "rich_dbt",
3469            include_str!("../tests/fixtures/dbt/detconfig-806cf2fa-rich_dbt.json"),
3470        ),
3471    ];
3472
3473    /// `Config::default()` with its three environment-backed fields
3474    /// (`HERMIT_EPOCH`, `HERMIT_PRNG`, `HERMIT_SCHED_SEED`) pinned, so the
3475    /// result does not depend on the test process's environment.
3476    fn env_free(epoch: &str, seed: &str) -> DetConfig {
3477        let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
3478        config.sched_seed = None;
3479        config
3480    }
3481
3482    fn default_config() -> DetConfig {
3483        env_free("--epoch=2026-01-01T00:00:00Z", "--seed=0")
3484    }
3485
3486    /// Non-default values in fields that serialize as strings, floats,
3487    /// options, and nested arrays. The path holds legacy anchor key names, so
3488    /// a substring-based insertion would put a key inside a string value.
3489    fn rich_config() -> DetConfig {
3490        let mut config = env_free("--epoch=2000-12-31T23:59:59Z", "--seed=7");
3491        config.rng_seed = Some(13);
3492        config.sched_seed = Some(11);
3493        config.clock_multiplier = Some(1.5);
3494        config.chaos = true;
3495        config.record_preemptions_to = Some(PathBuf::from(
3496            "/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
3497        ));
3498        config.mountinfo_root_rewrites = vec![MountInfoRootRewrite {
3499            raw_mount_id: 41,
3500            deterministic_root: b"/".to_vec(),
3501            raw_root_prefix: Some(b"/tmp/x".to_vec()),
3502            deterministic_root_prefix: Some(b"/tmp".to_vec()),
3503            raw_mountpoint_prefix: None,
3504            deterministic_mountpoint_prefix: None,
3505        }];
3506        config.stacktrace_event = vec![(3, Some(PathBuf::from("/s")))];
3507        config
3508    }
3509
3510    fn cases() -> [(&'static str, DetConfig); 3] {
3511        [
3512            ("default", default_config()),
3513            (
3514                "dbt",
3515                prepare_backend_config(default_config(), Backend::Dbt),
3516            ),
3517            (
3518                "rich_dbt",
3519                prepare_backend_config(rich_config(), Backend::Dbt),
3520            ),
3521        ]
3522    }
3523
3524    #[test]
3525    fn default_case_is_config_default_with_pinned_environment_fields() {
3526        let pinned = default_config();
3527        let from_default = DetConfig {
3528            epoch: pinned.epoch,
3529            seed: pinned.seed,
3530            sched_seed: pinned.sched_seed,
3531            ..DetConfig::default()
3532        };
3533        assert_eq!(
3534            serde_json::to_string(&from_default).unwrap(),
3535            serde_json::to_string(&pinned).unwrap()
3536        );
3537    }
3538
3539    #[test]
3540    fn dbt_detconfig_matches_806cf2fa_bytes() {
3541        for ((name, mut config), (golden_name, golden)) in cases().into_iter().zip(GOLDEN) {
3542            // Keep the historical capability value as well as its byte oracle.
3543            // Current DBT descriptor facts need the versioned transport below.
3544            config.backend.tool_shares_guest_descriptor_table = false;
3545            config.backend.rediscovers_descriptors_after_exec = false;
3546            // These three were `Config` fields, false unless the host set them
3547            // for the backend, until they became stated capabilities.
3548            config.backend.supports_blocked_wait_signal_interruption = false;
3549            config.backend.delivers_preemption_timer_events = false;
3550            config.backend.runs_guest_code_between_injections = false;
3551            assert_eq!(name, golden_name);
3552            let encoded = dbt_detconfig_json(&config).unwrap();
3553            assert_eq!(
3554                encoded, golden,
3555                "HERMIT_DBT_DETCONFIG for the {name} config differs from the 806cf2fa bytes"
3556            );
3557        }
3558    }
3559
3560    /// The DBT standalone fallback decodes the variable with
3561    /// `detcore::decode_backend_config_json` and falls back to its default
3562    /// config on a parse error. The three deleted switches' keys must be
3563    /// accepted and ignored, and the fifteen backend keys must decode back to
3564    /// the backend facts, so the runtime sees exactly the config that was
3565    /// encoded.
3566    #[test]
3567    fn dbt_detconfig_decodes_to_the_encoded_config() {
3568        for (name, config) in cases() {
3569            let encoded = dbt_detconfig_json(&config).unwrap();
3570            let decoded = detcore::decode_backend_config_json(&encoded)
3571                .unwrap_or_else(|error| panic!("{name}: DBT config does not decode: {error}"));
3572            assert_eq!(
3573                serde_json::to_string(&decoded).unwrap(),
3574                serde_json::to_string(&config).unwrap(),
3575                "{name}: decoded config differs from the encoded one"
3576            );
3577        }
3578    }
3579
3580    #[test]
3581    fn current_dbt_uses_exact_descriptor_facts_without_host_timed_turns() {
3582        let config = prepare_backend_config(default_config(), Backend::Dbt);
3583        assert!(config.backend.tool_shares_guest_descriptor_table);
3584        assert!(config.backend.rediscovers_descriptors_after_exec);
3585        assert!(!config.backend.internal_pipe_turns_are_host_timed);
3586        assert!(!config.backend.loopback_pollers_yield_to_peers);
3587        let encoded = dbt_detconfig_json(&config).unwrap();
3588        assert!(detcore::from_legacy_backend_json(&encoded).is_err());
3589        let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
3590        assert_eq!(decoded.backend, reverie::BackendCapabilities::DBT);
3591        assert_eq!(decoded.backend, config.backend);
3592    }
3593
3594    #[test]
3595    fn dbt_detconfig_keeps_descriptor_facts_independent() {
3596        // Exercise the real CLI encoder and the admitted standalone JSON
3597        // reader. In particular, descriptor discovery must not silently
3598        // opt into host-timed turns or loopback poller yielding.
3599        for mask in 0_u8..16 {
3600            let mut config = prepare_backend_config(default_config(), Backend::Dbt);
3601            config.backend.tool_shares_guest_descriptor_table = mask & 1 != 0;
3602            config.backend.rediscovers_descriptors_after_exec = mask & 2 != 0;
3603            config.backend.internal_pipe_turns_are_host_timed = mask & 4 != 0;
3604            config.backend.loopback_pollers_yield_to_peers = mask & 8 != 0;
3605            let encoded = dbt_detconfig_json(&config).unwrap();
3606            assert_eq!(
3607                detcore::from_legacy_backend_json(&encoded).is_ok(),
3608                mask == 0 || mask == 15,
3609                "only coupled facts fit the legacy form: mask {mask}"
3610            );
3611            let decoded = detcore::decode_backend_config_json(&encoded).unwrap();
3612            assert_eq!(decoded.backend, config.backend, "capability mask {mask}");
3613            assert_eq!(
3614                serde_json::to_string(&decoded).unwrap(),
3615                serde_json::to_string(&config).unwrap(),
3616                "configuration mask {mask}"
3617            );
3618        }
3619    }
3620
3621    #[test]
3622    fn representable_descriptor_facts_keep_the_current_config_bytes() {
3623        for discover in [false, true] {
3624            let mut config = prepare_backend_config(rich_config(), Backend::Dbt);
3625            config.backend.tool_shares_guest_descriptor_table = discover;
3626            config.backend.rediscovers_descriptors_after_exec = discover;
3627            config.backend.internal_pipe_turns_are_host_timed = discover;
3628            config.backend.loopback_pollers_yield_to_peers = discover;
3629            let legacy = detcore::to_legacy_backend_json(&config).unwrap();
3630            assert_eq!(
3631                dbt_detconfig_json(&config).unwrap(),
3632                insert_legacy_dbt_detconfig_keys(&legacy).unwrap()
3633            );
3634        }
3635    }
3636
3637    #[test]
3638    fn versioned_dbt_config_rejects_unknown_or_malformed_envelopes() {
3639        let config = prepare_backend_config(default_config(), Backend::Dbt);
3640        let legacy =
3641            insert_legacy_dbt_detconfig_keys(&detcore::to_legacy_backend_json(&config).unwrap())
3642                .unwrap();
3643        let legacy_backend = detcore::from_legacy_backend_json(&legacy).unwrap().backend;
3644        let backend = serde_json::to_string(&config.backend).unwrap();
3645        let envelope = |version: &str| {
3646            format!(
3647                "{{\"dbt_config_version\":{version},\"config\":{legacy},\"backend\":{backend}}}"
3648            )
3649        };
3650        for version in ["0", "2", "-1", "null", "\"1\""] {
3651            assert!(
3652                detcore::decode_backend_config_json(&envelope(version)).is_err(),
3653                "version {version} must be refused"
3654            );
3655            let tagged_legacy =
3656                legacy.replacen('{', &format!("{{\"dbt_config_version\":{version},"), 1);
3657            assert_eq!(
3658                detcore::decode_backend_config_json(&tagged_legacy)
3659                    .unwrap()
3660                    .backend,
3661                legacy_backend,
3662                "an unknown legacy key must remain ignored"
3663            );
3664        }
3665        let duplicate = format!(
3666            "{{\"dbt_config_version\":1,\"dbt_config_version\":1,\"config\":{legacy},\"backend\":{backend}}}"
3667        );
3668        assert!(detcore::decode_backend_config_json(&duplicate).is_err());
3669        let missing_backend = format!("{{\"dbt_config_version\":1,\"config\":{legacy}}}");
3670        assert!(detcore::decode_backend_config_json(&missing_backend).is_err());
3671        let missing_config = format!("{{\"dbt_config_version\":1,\"backend\":{backend}}}");
3672        assert!(detcore::decode_backend_config_json(&missing_config).is_err());
3673        for duplicate in [
3674            format!("\"config\":{legacy}"),
3675            format!("\"backend\":{backend}"),
3676            "\"unknown\":true".to_owned(),
3677        ] {
3678            let json = envelope("1").replacen('{', &format!("{{{duplicate},"), 1);
3679            assert!(detcore::decode_backend_config_json(&json).is_err());
3680        }
3681    }
3682
3683    #[test]
3684    fn legacy_key_insertion_refuses_a_missing_repeated_or_present_key() {
3685        let complete = r#"{"a":1,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3686        assert_eq!(
3687            insert_legacy_dbt_detconfig_keys(complete).unwrap(),
3688            concat!(
3689                r#"{"a":1,"use_thread_local_clock_reads":false,"#,
3690                r#""detect_host_clock_futex_timeouts":false,"#,
3691                r#""backend_serializes_fork_children":false,"#,
3692                r#""backend_dispatches_thread_tools":true,"#,
3693                r#""backend_tracks_process_children":true}"#,
3694            )
3695        );
3696
3697        let missing = r#"{"detect_host_clock_futex_timeouts":false}"#;
3698        let error = insert_legacy_dbt_detconfig_keys(missing).unwrap_err();
3699        assert!(
3700            error.to_string().contains("appears 0 times"),
3701            "unexpected error: {error}"
3702        );
3703
3704        let repeated = r#"{"detect_host_clock_futex_timeouts":false,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3705        let error = insert_legacy_dbt_detconfig_keys(repeated).unwrap_err();
3706        assert!(
3707            error.to_string().contains("appears 2 times"),
3708            "unexpected error: {error}"
3709        );
3710
3711        let present = r#"{"use_thread_local_clock_reads":true,"detect_host_clock_futex_timeouts":false,"backend_tracks_process_children":true}"#;
3712        let error = insert_legacy_dbt_detconfig_keys(present).unwrap_err();
3713        assert!(
3714            error.to_string().contains("already present"),
3715            "unexpected error: {error}"
3716        );
3717    }
3718}
3719
3720/// The program a DBT launch runs and the working directory it runs from, as
3721/// reverie-dbt's launcher finds them: a name without a `/` through `path`,
3722/// whose relative entries are taken from the guest's working directory;
3723/// `cwd` relative to `current` (the launcher's own directory) when it is
3724/// relative, and `current` when there is none. `None` where the search finds
3725/// no executable file.
3726#[cfg(feature = "dbt")]
3727fn dbt_launched_program(
3728    program: &std::path::Path,
3729    cwd: Option<&std::path::Path>,
3730    path: Option<&std::ffi::OsStr>,
3731    current: &std::path::Path,
3732) -> Option<(PathBuf, PathBuf)> {
3733    use std::os::unix::ffi::OsStrExt;
3734    use std::os::unix::fs::PermissionsExt;
3735    let cwd = cwd.map_or_else(|| current.to_owned(), |cwd| current.join(cwd));
3736    let spelled = if program.as_os_str().as_bytes().contains(&b'/') {
3737        program.to_owned()
3738    } else {
3739        std::env::split_paths(path?)
3740            .map(|directory| cwd.join(directory).join(program))
3741            .find(|candidate| {
3742                candidate.metadata().is_ok_and(|metadata| {
3743                    metadata.is_file() && metadata.permissions().mode() & 0o111 != 0
3744                })
3745            })?
3746    };
3747    Some((spelled, cwd))
3748}
3749
3750#[cfg(all(test, feature = "dbt"))]
3751mod dbt_launched_program_tests {
3752    use std::os::unix::fs::PermissionsExt;
3753
3754    use super::*;
3755
3756    fn executable(path: &std::path::Path) {
3757        std::fs::create_dir_all(path.parent().unwrap()).unwrap();
3758        std::fs::write(path, b"").unwrap();
3759        std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o755)).unwrap();
3760    }
3761
3762    #[test]
3763    fn a_relative_path_entry_is_taken_from_the_guests_directory_not_the_launchers() {
3764        let root = tempfile::tempdir().unwrap();
3765        let launcher_dir = root.path().join("launcher");
3766        // A decoy where the launcher's own directory would find it, and the
3767        // program where the guest's directory does.
3768        executable(&launcher_dir.join("bin/prog"));
3769        executable(&root.path().join("guest/bin/prog"));
3770        std::fs::write(root.path().join("guest/plain"), b"").unwrap();
3771        let path = std::ffi::OsStr::new("bin");
3772        let found = |program: &str, cwd: Option<&str>| {
3773            dbt_launched_program(
3774                std::path::Path::new(program),
3775                cwd.map(std::path::Path::new),
3776                Some(path),
3777                &launcher_dir,
3778            )
3779        };
3780        let guest = root.path().join("guest");
3781        // An absolute and a relative working directory find the same file.
3782        let expected = Some((guest.join("bin/prog"), guest.clone()));
3783        assert_eq!(found("prog", Some(guest.to_str().unwrap())), expected);
3784        assert_eq!(
3785            found("prog", Some("../guest")),
3786            Some((
3787                launcher_dir.join("../guest/bin/prog"),
3788                launcher_dir.join("../guest")
3789            ))
3790        );
3791        // Without a working directory, the launcher's own is the guest's.
3792        assert_eq!(
3793            found("prog", None),
3794            Some((launcher_dir.join("bin/prog"), launcher_dir.clone()))
3795        );
3796        // A name with a `/` is not searched for.
3797        assert_eq!(
3798            found("./plain", Some(guest.to_str().unwrap())),
3799            Some((std::path::PathBuf::from("./plain"), guest.clone()))
3800        );
3801        // A file that is not executable is not found.
3802        assert_eq!(found("plain", Some(guest.to_str().unwrap())), None);
3803    }
3804}
3805
3806/// Records, for a DBT run, the guest's first image: `program`, found and
3807/// run from `cwd` with the guest's `PATH`, `path`, as the launch finds it
3808/// (`dbt_launched_program`), then resolved as the kernel resolves an
3809/// `execve`. Both DBT launch paths call it in the container, whose root is
3810/// the guest's, in place of `launched_image`'s search, which takes a
3811/// relative `PATH` entry from the coordinator's directory rather than the
3812/// guest's. Where nothing is found the record stays unset, and the image's
3813/// own `AT_EXECFN` gives it after the exec.
3814#[cfg(feature = "dbt")]
3815pub fn record_dbt_launched_image(
3816    config: &mut DetConfig,
3817    program: &std::path::Path,
3818    cwd: Option<&std::path::Path>,
3819    path: Option<&std::ffi::OsStr>,
3820) {
3821    let exe = std::env::current_dir()
3822        .ok()
3823        .and_then(|current| dbt_launched_program(program, cwd, path, &current))
3824        .and_then(|(spelled, cwd)| {
3825            detcore::exec_record::ExecRecord::resolve(std::path::Path::new("/"), &cwd, &spelled)
3826        })
3827        .map(|record| record.exe);
3828    config
3829        .launch_image
3830        .get_or_insert(detcore::LaunchImage {
3831            exe: None,
3832            launcher: None,
3833        })
3834        .exe = exe;
3835}
3836
3837/// Declares, for a DBT run through `drrun`, the image the kernel execs in the
3838/// guest's place: DynamoRIO's library (`lib64/release/libdynamorio.so` beside
3839/// `drrun`'s `bin64`), which loads the guest itself. So the kernel's `exe`
3840/// link and program break are DynamoRIO's (`detcore::LaunchImage::launcher`),
3841/// and Detcore answers the guest's brk from its own model; the runner tells
3842/// DynamoRIO to reserve nothing for the break
3843/// (`reverie_dbt::DbtRunner::tool_answers_brk`).
3844/// An error where that library is missing: the run would otherwise
3845/// declare a launcher the kernel never execs, and refuse every brk for want
3846/// of a record the launcher check can accept.
3847#[cfg(feature = "dbt")]
3848pub fn declare_dbt_launcher(config: &mut DetConfig, drrun: &std::path::Path) -> Result<(), Error> {
3849    let library = drrun
3850        .parent()
3851        .and_then(std::path::Path::parent)
3852        .unwrap_or(std::path::Path::new("/"))
3853        .join("lib64/release/libdynamorio.so");
3854    if !library.is_file() {
3855        return Err(anyhow!(
3856            "DynamoRIO's library is not at {} beside drrun {}",
3857            library.display(),
3858            drrun.display()
3859        ));
3860    }
3861    config
3862        .launch_image
3863        .get_or_insert(detcore::LaunchImage {
3864            exe: None,
3865            launcher: None,
3866        })
3867        .launcher = Some(library);
3868    Ok(())
3869}
3870
3871// AUTONOMOUS-BOT-IMPLEMENTED
3872// TODO-HUMAN-REVIEW(PR-737): Review public DBT dispatch and child environment ownership.
3873/// Dispatch a command onto the Detcore-linked reverie-dbt runtime.
3874#[cfg(feature = "dbt")]
3875async fn run_dbt(
3876    command: Command,
3877    config: DetConfig,
3878    print_summary: bool,
3879    capture_output: bool,
3880) -> Result<Output, Error> {
3881    if !config.sequentialize_threads {
3882        return Err(anyhow!(
3883            "the dbt backend requires sequentialized threads; remove \
3884             --no-sequentialize-threads (or --strace-only) to run under --backend dbt"
3885        ));
3886    }
3887
3888    // The guest sees this string in its environment, so it keeps the encoding
3889    // it had before the backend facts moved into `Config::backend` and before
3890    // three constant switches were deleted; see `dbt_detconfig_json`. The DBT
3891    // runtime decodes the backend facts back out of it (here DBT's own); when
3892    // the string is absent or does not parse, it uses the strict default's
3893    // facts, which are ptrace's.
3894    let (drrun, client) = detcore_dbt::prepare_native_client()
3895        .map_err(|error| anyhow!("failed to prepare the Detcore DynamoRIO client: {error}"))?;
3896    let mut config = config;
3897    declare_dbt_launcher(&mut config, &drrun)?;
3898    record_dbt_launched_image(
3899        &mut config,
3900        std::path::Path::new(command.get_program()),
3901        command.get_current_dir(),
3902        command
3903            .get_captured_envs()
3904            .get(std::ffi::OsStr::new("PATH"))
3905            .map(std::ffi::OsString::as_os_str),
3906    );
3907    let config_json = dbt_detconfig_json(&config)
3908        .map_err(|error| anyhow!("failed to serialize the Detcore config for DBT: {error}"))?;
3909    let panic_on_unsupported_syscalls = config.panic_on_unsupported_syscalls;
3910    // Bind native diagnostics to the controller before guest output capture.
3911    let diagnostics = std::fs::File::from(
3912        std::io::stderr()
3913            .as_fd()
3914            .try_clone_to_owned()
3915            .map_err(|error| anyhow!("failed to retain DBT diagnostic stderr: {error}"))?,
3916    );
3917    let mut runner = reverie_dbt::DbtRunner::new(&drrun, &client)
3918        .map_err(|error| {
3919            anyhow!(
3920                "failed to configure the DynamoRIO DBT runner (drrun={}, client={}): {error}",
3921                drrun.display(),
3922                client.display()
3923            )
3924        })?
3925        .summary(print_summary)
3926        .isolated_process_group(panic_on_unsupported_syscalls)
3927        .tool_answers_brk(true)
3928        .diagnostic_file(&diagnostics)
3929        .map_err(|error| anyhow!("failed to configure DBT diagnostic stderr: {error}"))?;
3930    drop(diagnostics);
3931    if panic_on_unsupported_syscalls {
3932        runner = runner.client_argument("-panic-on-unsupported-syscalls");
3933    }
3934
3935    let program = command.get_program().to_owned();
3936    let mut environment = command.get_captured_envs();
3937    environment.insert(detcore_dbt::DETCONFIG_ENV.into(), config_json.into());
3938    let guest = command.into_std_lossy();
3939    tracing::info!(
3940        target: "hermit::dbt",
3941        program = ?program,
3942        drrun = %drrun.display(),
3943        client = %client.display(),
3944        "launching guest through reverie-dbt with Detcore<DbtGuest>",
3945    );
3946
3947    let (status, stdout, stderr, mut global) = if capture_output {
3948        let launch = || {
3949            runner.output_with_environment_and_global::<detcore::GlobalState>(
3950                &guest,
3951                &environment,
3952                config.clone(),
3953            )
3954        };
3955        let (mut output, mut global) = launch()
3956            .await
3957            .map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
3958        if dbt_client_thread_start_failed(&output.status) {
3959            tracing::warn!(
3960                target: "hermit::dbt",
3961                "DynamoRIO client thread failed before guest start; retrying once",
3962            );
3963            global.force_shutdown_with_error();
3964            global.cancel_internal_scheduler().await;
3965            global.clean_up(false, &None).await;
3966            (output, global) = launch().await.map_err(|error| {
3967                anyhow!("failed to launch drrun ({}): {error}", drrun.display())
3968            })?;
3969        }
3970        (output.status, output.stdout, output.stderr, global)
3971    } else {
3972        let launch = || {
3973            runner.status_with_environment_and_global::<detcore::GlobalState>(
3974                &guest,
3975                &environment,
3976                config.clone(),
3977            )
3978        };
3979        let (mut status, mut global) = launch()
3980            .await
3981            .map_err(|error| anyhow!("failed to launch drrun ({}): {error}", drrun.display()))?;
3982        if dbt_client_thread_start_failed(&status) {
3983            tracing::warn!(
3984                target: "hermit::dbt",
3985                "DynamoRIO client thread failed before guest start; retrying once",
3986            );
3987            global.force_shutdown_with_error();
3988            global.cancel_internal_scheduler().await;
3989            global.clean_up(false, &None).await;
3990            (status, global) = launch().await.map_err(|error| {
3991                anyhow!("failed to launch drrun ({}): {error}", drrun.display())
3992            })?;
3993        }
3994        (status, Vec::new(), Vec::new(), global)
3995    };
3996
3997    if !status.success() {
3998        global.force_shutdown_with_error();
3999        global.cancel_internal_scheduler().await;
4000    }
4001    global.clean_up(print_summary, &None).await;
4002    Ok(Output {
4003        status: status.into(),
4004        stdout,
4005        stderr,
4006    })
4007}
4008
4009// NOTE: A single-threaded executor is used here so that the tokio threads
4010// themselves wouldn't contribute non-determinism to the PID namespace. This
4011// could also be changed to a specific number of threads and that would be
4012// deterministic, but it shouldn't be based on the number of cores. When the
4013// thread count is based off of the number of cores in the machine, then two
4014// runs on different machines with a different number of cores will not be the
4015// same.
4016/// Run the given command as deterministically as possible.
4017///
4018/// # Stack size
4019///
4020/// On the ptrace backend this and the other launch functions (`run*`,
4021/// `record*`, `replay*`, [`HermitData::record`]) run the whole ptrace session
4022/// on a tracer thread of their own, with an 8 MiB stack (the main thread's
4023/// usual size, the default `ulimit -s`), so the calling thread needs no
4024/// particular stack: a recording through the library returned on a 95 KiB
4025/// caller thread. One tracer thread serves each calling thread for the
4026/// caller's lifetime, so an operation kept at a [`HermitCleanupUnconfirmed`]
4027/// checkpoint is resumed from the same caller. That thread stays, idle, until
4028/// the caller exits, and a tracing subscriber set for the calling thread only
4029/// does not see the session's events (a global subscriber does). The session itself, in a debug
4030/// build, needs about 2 MiB, mostly Detcore's syscall handler, which at
4031/// opt-level 0 keeps every syscall arm's temporaries in one frame
4032/// (<https://github.com/rrnewton/hermit/issues/4389>).
4033///
4034/// The other backends still run on the calling thread, which then needs that
4035/// stack itself: launching from a thread spawned with 4 MiB
4036/// (`std::thread::Builder::stack_size`) is recommended for them, and Rust's
4037/// default 2 MiB for a spawned thread or a test is not enough in a debug build
4038/// with the `third-party-backends` feature. Optimised builds need much less:
4039/// in the `validate` profile a 512 KiB thread was enough.
4040pub fn run(
4041    command: Command,
4042    config: DetConfig,
4043    print_summary: bool,
4044    print_summary_to_json_file: &Option<PathBuf>,
4045) -> Result<ExitStatus, Error> {
4046    run_with_backend(
4047        command,
4048        config,
4049        print_summary,
4050        print_summary_to_json_file,
4051        Backend::Ptrace,
4052    )
4053}
4054
4055/// Run the given command using the selected instrumentation backend.
4056///
4057/// On ptrace it needs no particular stack from the calling thread; see [`run`].
4058pub fn run_with_backend(
4059    command: Command,
4060    config: DetConfig,
4061    print_summary: bool,
4062    print_summary_to_json_file: &Option<PathBuf>,
4063    backend: Backend,
4064) -> Result<ExitStatus, Error> {
4065    run_with_backend_timeout(
4066        command,
4067        config,
4068        print_summary,
4069        print_summary_to_json_file,
4070        backend,
4071        None,
4072    )
4073}
4074
4075/// [`run_with_backend`] with a hermit-enforced wall-clock bound on the guest.
4076///
4077/// On ptrace it needs no particular stack from the calling thread; see [`run`].
4078///
4079/// This library never installs a process alarm. Ordinary ptrace keeps the
4080/// original runtime, operation, failed GlobalState and backing guards when a
4081/// finite cleanup attempt is unconfirmed; downcast [`HermitCleanupUnconfirmed`]
4082/// and recover it on the original process/thread. A timeout is measured before
4083/// startup and is not a certificate of cleanup. `None` leaves execution
4084/// unbounded, but fatal cleanup attempts remain finite. Nonordinary backends
4085/// retain their existing cooperative timeout/drop semantics. Synchronous stalls
4086/// require caller-owned supervision; only the CLI owns its hard alarm fallback.
4087///
4088/// ⚠️ NOT PART OF `DetConfig`, DELIBERATELY. A wall-clock bound is host state,
4089/// and `DetConfig` is the determinism configuration that is serialized to disk
4090/// and reasoned about as guest-visible. Threading a real-time deadline through
4091/// it would put a nondeterministic quantity inside the structure whose entire
4092/// job is to exclude them.
4093pub fn run_with_backend_timeout(
4094    command: Command,
4095    config: DetConfig,
4096    print_summary: bool,
4097    print_summary_to_json_file: &Option<PathBuf>,
4098    backend: Backend,
4099    timeout: Option<Duration>,
4100) -> Result<ExitStatus, Error> {
4101    if backend == Backend::Ptrace {
4102        let summary_path = print_summary_to_json_file.clone();
4103        let command = tracer_thread::SendCommand::new(command);
4104        return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4105            let command = command.into_inner();
4106            let report = SkidOvershootReport::begin(true);
4107            let config = prepare_backend_config(config, backend);
4108            let result = dispatch_backend(
4109                command,
4110                config,
4111                print_summary,
4112                &summary_path,
4113                backend,
4114                Some(control),
4115            )
4116            .await;
4117            report.finish(result)
4118        });
4119    }
4120    let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
4121    if backend == Backend::Kvm {
4122        ensure_kvm_stdin_reserved()?;
4123    }
4124    let config = prepare_backend_config(config, backend);
4125    let result = run_with_backend_inner(
4126        command,
4127        config,
4128        print_summary,
4129        print_summary_to_json_file,
4130        backend,
4131        timeout,
4132    );
4133    skid_overshoot_report.finish(result)
4134}
4135
4136// TODO-HUMAN-REVIEW(PR-749): Review LiteInst backend configuration normalization.
4137#[doc(hidden)]
4138pub fn prepare_backend_config(mut config: DetConfig, backend: Backend) -> DetConfig {
4139    // Detcore reads what the selected backend can do, never which backend it is.
4140    // Each backend states its own facts in `Backend::capabilities()`.
4141    //
4142    // Three properties hold on every backend, so they are not capabilities:
4143    // - Guest-visible wall and monotonic clocks stay in the same global
4144    //   virtual-time domain as timers, sleeps, and timeout deadlines. SaBRe's
4145    //   per-thread execution clock does not advance when the scheduler skips
4146    //   global time while a thread is blocked.
4147    // - A forked process child runs concurrently with its parent. Detcore
4148    //   blocks the parent only for CLONE_VFORK.
4149    // - Detcore dispatches every cloned thread's syscalls through its tool.
4150    // AUTONOMOUS-BOT-IMPLEMENTED
4151    // TODO-HUMAN-REVIEW(PR-845): Review backend-local guest clock observations.
4152    // TODO-HUMAN-REVIEW(PR-1013): Review backend child process execution ordering.
4153    // TODO-HUMAN-REVIEW(PR-1013): Review backend thread callback coverage.
4154    // TODO-HUMAN-REVIEW(PR-1122): Review concurrent KVM process-child scheduling.
4155    // AUTONOMOUS-BOT-IMPLEMENTED
4156    // TODO-HUMAN-REVIEW(PR-3635): Review in-guest LiteInst killed-thread RPC cancellation.
4157    // AUTONOMOUS-BOT-IMPLEMENTED
4158    // TODO-HUMAN-REVIEW(PR-1152): KVM defers the vfork child spawn, so the child
4159    // registers its vfork barrier only after the parent posts BlockedExternalContinue. ptrace keeps
4160    // the parent kernel-blocked until the child registers.
4161    config.backend = backend_capabilities(backend);
4162    // Whether the run's process signals are tool-controlled is not decided
4163    // here: Detcore installs the backend's process signal control when the
4164    // backend offers it and threads are sequentialized, and reads the installed
4165    // control from then on.
4166    // Whether blocked waits decide signal interruption from the kernel's
4167    // signal state (https://github.com/rrnewton/hermit/issues/3146), whether a
4168    // `--max-timeslice` really preempts (https://github.com/rrnewton/hermit/issues/4068)
4169    // and whether guest code can run between two injected calls are the
4170    // backend's own stated facts in `config.backend`
4171    // (`supports_blocked_wait_signal_interruption`,
4172    // `delivers_preemption_timer_events`, `runs_guest_code_between_injections`),
4173    // not derived from its name here (audit step A9 of
4174    // https://github.com/rrnewton/hermit/issues/4485).
4175    // Only backends where Detcore treats a terminal's signals as reaching the
4176    // guest from the host read it (`Config::guest_may_inherit_a_terminal`, the
4177    // legacy bundled condition
4178    // `bundled_signal_facts::host_timed_signal_sources_are_physical`), so the
4179    // host is asked only for them.
4180    config.guest_may_inherit_a_terminal =
4181        bundled_signal_facts::host_timed_signal_sources_are_physical(&config.backend)
4182            && launcher_may_pass_a_terminal();
4183    config
4184}
4185
4186/// Whether the guest may start with a terminal, which can make Linux send the
4187/// guest signals at moments the host sets, such as SIGHUP when the terminal
4188/// hangs up and SIGWINCH when it is resized
4189/// (`Config::guest_may_inherit_a_terminal`): one of this process's standard
4190/// descriptors, which the guest inherits, is a terminal, or this process has a
4191/// controlling terminal, which the guest inherits with its session because
4192/// neither Hermit nor Reverie starts a new session for it. When the
4193/// controlling terminal cannot be read, the answer is yes.
4194fn launcher_may_pass_a_terminal() -> bool {
4195    // SAFETY: isatty only inspects the descriptor.
4196    let standard_terminal = (0..=2).any(|fd| unsafe { libc::isatty(fd) } == 1);
4197    may_pass_a_terminal(standard_terminal, controlling_terminal_device())
4198}
4199
4200/// The rule of `launcher_may_pass_a_terminal`: a terminal standard descriptor,
4201/// a controlling terminal (a nonzero device number), or an unknown one.
4202fn may_pass_a_terminal(standard_terminal: bool, controlling_terminal: Option<i64>) -> bool {
4203    standard_terminal || controlling_terminal != Some(0)
4204}
4205
4206/// This process's controlling terminal as `/proc/self/stat` reports it: field
4207/// 7, `tty_nr`, the terminal's device number, or 0 when there is none. `None`
4208/// when it cannot be read.
4209fn controlling_terminal_device() -> Option<i64> {
4210    parse_controlling_terminal_device(&std::fs::read_to_string("/proc/self/stat").ok()?)
4211}
4212
4213/// `tty_nr` from the text of a `/proc/<pid>/stat` file. The command name in
4214/// field 2 is parenthesized and may hold spaces and parentheses, so the fields
4215/// after it are counted from its last `)`: state, ppid, pgrp, session, tty_nr.
4216fn parse_controlling_terminal_device(stat: &str) -> Option<i64> {
4217    let after_command = stat.get(stat.rfind(')')? + 1..)?;
4218    after_command.split_ascii_whitespace().nth(4)?.parse().ok()
4219}
4220
4221/// What the selected backend can do, as Detcore consumes it.
4222///
4223/// Backends whose crate is always linked are asked directly. The LiteInst and
4224/// DBT constants are checked against their crates by tests built with those
4225/// features; the SaBRe value has no such check. e9patch takes ptrace's.
4226#[doc(hidden)]
4227pub fn backend_capabilities(backend: Backend) -> reverie::BackendCapabilities {
4228    match backend {
4229        // e9patch is binary-rewriting preprocessing whose guest runs on the
4230        // ptrace backend (`hermit run --backend=e9patch` configures its run as
4231        // `Backend::Ptrace`), so it has ptrace's capabilities. A direct caller
4232        // used to get two of them turned off by this name.
4233        Backend::Ptrace | Backend::E9patch => {
4234            <reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
4235        }
4236        Backend::Kvm => reverie_kvm::KvmBackend::capabilities(),
4237        // Site patching changes how a syscall reaches the Tool, not what the
4238        // Tool host can do, so in-guest-trap has in-guest LiteInst's capabilities.
4239        Backend::Liteinst | Backend::InGuestTrap => reverie::BackendCapabilities::LITEINST_IN_GUEST,
4240        Backend::Sabre => reverie::BackendCapabilities::SABRE,
4241        Backend::Dbt => reverie::BackendCapabilities::DBT,
4242    }
4243}
4244
4245/// Whether `backend`'s runtime arms Reverie ptrace's PMU timer and delivers its
4246/// events, so `--max-timeslice` really preempts a thread that makes no syscall:
4247/// the backend's stated `delivers_preemption_timer_events`. Only ptrace does
4248/// (e9patch preprocessing runs on it). SaBRe and KVM accept a timer request and
4249/// deliver nothing; DBT and in-guest LiteInst refuse it.
4250pub fn backend_delivers_preemption_timer(backend: Backend) -> bool {
4251    backend_capabilities(backend).delivers_preemption_timer_events
4252}
4253
4254/// After an in-guest LiteInst run, waits (bounded) until the watcher has
4255/// reported every admitted process's physical exit, then releases any exit
4256/// barrier still recorded. Release comes only after that drain: an exit still
4257/// in flight is reported first.
4258///
4259/// Every report is applied again to the run's returned state. The backend
4260/// lets go of its own reference to that state when the run ends, and a report
4261/// that arrived afterwards reached nothing; applying a report twice consumes
4262/// nothing the second time.
4263///
4264/// A failed drain, a fired watchdog or a refused admission fails the run:
4265/// it records a determinism loss, so verification refuses to compare it, and
4266/// returns the failure, after the barriers are released.
4267#[cfg(feature = "liteinst")]
4268async fn settle_in_guest_exits(
4269    exits: &in_guest_exits::InGuestExitAdmission,
4270    global_state: &detcore::GlobalState,
4271) -> Result<(), Error> {
4272    let drained = exits.drain(std::time::Duration::from_secs(10)).await;
4273    for pid in exits.reported_exits() {
4274        global_state.complete_physical_process_exit(pid);
4275    }
4276    global_state.release_all_physical_process_exits();
4277    let failure = exits.failure().or_else(|| {
4278        drained
4279            .err()
4280            .map(|error| format!("not every in-guest LiteInst guest exit was reported: {error:?}"))
4281    });
4282    match failure {
4283        Some(reason) => {
4284            detcore::detlog::record_determinism_loss(&reason);
4285            Err(Error::msg(reason))
4286        }
4287        None => Ok(()),
4288    }
4289}
4290
4291// TODO-HUMAN-REVIEW(PR-736): Review reserved LiteInst runtime failure statuses.
4292//
4293// ⚠️ THIS PREDICATE AND THE CLASSIFIER MUST AGREE ABOUT THE SIGNAL BAND, AND A
4294// HARD-CODED RANGE CANNOT. They do NOT cover the same statuses and are not meant
4295// to -- see the table below for what each covers. It is the SIGNAL half that has
4296// to move together, because both readers derive it from the same fact. When the reserved set grew to include the signal
4297// band, `Exited(130)` fell outside `122..=127` and is NOT `Signaled(_, _)` --
4298// it is a status hermit CHOSE, not an actual signal death -- so LiteInst
4299// skipped the forced shutdown and `clean_up` could wait forever on
4300// `handle.await` (detcore/src/tool_global.rs). The reserved set had grown past
4301// the range this hard-coded, and nothing connected the two.
4302//
4303// Keying the SIGNAL HALF on `signal_from_exit_status` -- the same predicate
4304// `classify_container_result` uses -- is what stops that half drifting again: a
4305// change to the band moves both readers or neither.
4306//
4307// ⚠️ THE TWO PREDICATES ARE NOT THE SAME SET, AND AN EARLIER VERSION OF THIS
4308// COMMENT SAID THEY WERE. agent(hermit-007)'s codex lane caught the overclaim.
4309// They deliberately differ:
4310//
4311//   this predicate            122..=127        +  signal band  +  real Signaled
4312//   classify_container_result 122 + 123 + 124  +  signal band
4313//
4314// 123..=127 force a LiteInst shutdown and are classified as NEITHER a refusal
4315// nor a signal death. The classifier gives 123 and 124 arms of their own -- 123
4316// is the log byte cap (hermit's `--max-log-bytes`, and the value reserved for
4317// safehermit's log-cap kill, which still exits 125), 124 a deadline hermit
4318// enforced -- while 125 (hermit itself) and 126/127 (exec-level) have none, and
4319// each has a different producer. Only the signal half is shared, and only the
4320// signal half is protected from drift. Do not "simplify" this by assuming the
4321// two agree; the `122..=127` bound here is still hard-coded and still needs a
4322// human to widen it if the reserved set grows again.
4323#[cfg(feature = "liteinst")]
4324fn liteinst_requires_forced_shutdown(status: ExitStatus) -> bool {
4325    match status {
4326        // A real signal death: the process never chose a status at all.
4327        ExitStatus::Signaled(_, _) | ExitStatus::SignaledRaw(_, _) => true,
4328        ExitStatus::Exited(code) => {
4329            // The 122..=127 reserved band, plus any status hermit emits to mean
4330            // "killed by signal N".
4331            (122..=127).contains(&code) || detcore_model::signal_from_exit_status(code).is_some()
4332        }
4333    }
4334}
4335
4336/// The guest outlived the wall-clock bound the caller asked hermit to enforce.
4337///
4338/// A DISTINCT TYPE, NOT A STRING, because `failure_exit_code` and
4339/// `classify_failure` both have to recognise it and a prose match would break
4340/// silently the first time the wording changed.
4341#[derive(Debug)]
4342pub struct GuestTimedOut {
4343    /// The bound that was exceeded, as the caller spelled it.
4344    pub limit: Duration,
4345}
4346
4347impl std::fmt::Display for GuestTimedOut {
4348    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
4349        write!(
4350            f,
4351            "Guest exceeded the --timeout bound of {} seconds",
4352            self.limit.as_secs()
4353        )
4354    }
4355}
4356
4357impl std::error::Error for GuestTimedOut {}
4358
4359/// Nonordinary backends retain their existing cooperative timeout behavior.
4360/// There is no process-wide alarm in this library. A caller needing a bound on
4361/// synchronous stalls must own external supervision; the CLI arms its own
4362/// separate init-process fallback before invoking the library. Ordinary ptrace
4363/// uses the retained whole-operation driver instead of cancelling this future.
4364async fn with_run_deadline<F>(timeout: Option<Duration>, guest: F) -> Result<ExitStatus, Error>
4365where
4366    F: std::future::Future<Output = Result<ExitStatus, Error>>,
4367{
4368    match timeout {
4369        None => guest.await,
4370        Some(limit) => match tokio::time::timeout(limit, guest).await {
4371            Ok(result) => result,
4372            Err(_) => Err(Error::new(GuestTimedOut { limit })),
4373        },
4374    }
4375}
4376
4377#[tokio::main(flavor = "current_thread")]
4378async fn run_with_backend_inner(
4379    command: Command,
4380    config: DetConfig,
4381    print_summary: bool,
4382    print_summary_to_json_file: &Option<PathBuf>,
4383    backend: Backend,
4384    timeout: Option<Duration>,
4385) -> Result<ExitStatus, Error> {
4386    refuse_in_guest_liteinst_timeout(backend, timeout)?;
4387    // Keep the large backend future off the container supervisor's stack
4388    // before the deadline and Tokio wrappers capture it. Polling and dropping
4389    // stay inline, including the backend teardown on timeout.
4390    let guest = Box::pin(dispatch_backend(
4391        command,
4392        config,
4393        print_summary,
4394        print_summary_to_json_file,
4395        backend,
4396        None,
4397    ));
4398    with_run_deadline(timeout, guest).await
4399}
4400
4401/// The guest's first image, as its `/proc/self/exe` link names it
4402/// (`detcore::Config::launch_image`): the program the launch executes, found
4403/// as the launch finds it, then resolved as the kernel resolves an `execve`
4404/// (`detcore::exec_record::ExecRecord::resolve`). Read in the container,
4405/// whose root is the guest's. A launch through a launcher names it itself
4406/// (`run_sabre`). `None` when it cannot be found, which leaves the link to the
4407/// kernel, and the launch reports the missing program itself.
4408fn launched_image(command: &Command) -> Option<detcore::LaunchImage> {
4409    let program = command.find_program().ok()?;
4410    let cwd = match command.get_current_dir() {
4411        Some(cwd) => cwd.to_owned(),
4412        None => std::env::current_dir().ok()?,
4413    };
4414    let record = detcore::exec_record::ExecRecord::resolve(Path::new("/"), &cwd, &program)?;
4415    Some(detcore::LaunchImage {
4416        exe: Some(record.exe),
4417        launcher: None,
4418    })
4419}
4420
4421async fn dispatch_backend(
4422    command: Command,
4423    mut config: DetConfig,
4424    print_summary: bool,
4425    print_summary_to_json_file: &Option<PathBuf>,
4426    backend: Backend,
4427    control: Option<std::rc::Rc<ptrace_completion::Control>>,
4428) -> Result<ExitStatus, Error> {
4429    // Every launch path, ptrace's included, reaches the guest through here.
4430    crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
4431    config.launch_image = launched_image(&command);
4432    if backend == Backend::Kvm {
4433        return Ok(run_kvm(
4434            &command,
4435            config,
4436            print_summary,
4437            print_summary_to_json_file,
4438            false,
4439        )
4440        .await?
4441        .status);
4442    }
4443    if backend == Backend::Dbt {
4444        #[cfg(feature = "dbt")]
4445        {
4446            return Ok(run_dbt(command, config, print_summary, false).await?.status);
4447        }
4448        #[cfg(not(feature = "dbt"))]
4449        {
4450            backend.ensure_available()?;
4451            unreachable!("DBT availability must fail when the feature is disabled");
4452        }
4453    }
4454    if backend == Backend::Sabre {
4455        return Ok(run_sabre(
4456            command,
4457            config,
4458            print_summary,
4459            print_summary_to_json_file,
4460            false,
4461        )
4462        .await?
4463        .status);
4464    }
4465    if backend.is_in_guest_liteinst() {
4466        #[cfg(feature = "liteinst")]
4467        {
4468            let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
4469            let mut command = command;
4470            refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
4471            let (launch, _detlog_descriptor) =
4472                in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
4473            let tool_data = launch.encode();
4474            // Every Tool image must forward on that socket, by that policy;
4475            // see detcore::Config::in_guest_detlog_forward_policy.
4476            let mut config = config;
4477            config.in_guest_detlog_forward_policy = _detlog_descriptor
4478                .is_some()
4479                .then(|| in_guest_detlog_forward_policy().encode());
4480            config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
4481            let preload = liteinst_tool_runtime_library_path()?;
4482            let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
4483            let (exit_status, mut global_state, dispatch_stats, process_reports) =
4484                reverie_liteinst::LiteinstBackend::with_connection_admission(
4485                    exits.clone(),
4486                    async {
4487                        if stats_request.is_enabled() {
4488                            let (exit_status, global_state, source) =
4489                                reverie_liteinst::LiteinstBackend::run_with_preload_data_and_stats::<
4490                                    Detcore,
4491                                >(command, config, preload, tool_data)
4492                                .await?;
4493                            let dispatch_stats =
4494                                backend_stats::report(backend, stats_request, &source);
4495                            let process_reports = source.snapshot().process_reports();
4496                            Ok::<_, reverie::Error>((
4497                                exit_status,
4498                                global_state,
4499                                dispatch_stats,
4500                                process_reports,
4501                            ))
4502                        } else {
4503                            let (exit_status, global_state) =
4504                                reverie_liteinst::LiteinstBackend::run_with_preload_data::<Detcore>(
4505                                    command, config, preload, tool_data,
4506                                )
4507                                .await?;
4508                            Ok((exit_status, global_state, None, 0))
4509                        }
4510                    },
4511                )
4512                .await
4513                .inspect_err(|error| exits.fail_launch(error))?;
4514            let patched =
4515                in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
4516            let settled = settle_in_guest_exits(&exits, &global_state).await;
4517            let policy_refusal = global_state.policy_refusal();
4518            if settled.is_err() || liteinst_requires_forced_shutdown(exit_status) {
4519                global_state.force_shutdown_with_error();
4520                global_state.cancel_internal_scheduler().await;
4521            }
4522            global_state
4523                .clean_up_with_dispatch_stats(
4524                    print_summary,
4525                    print_summary_to_json_file,
4526                    dispatch_stats,
4527                )
4528                .await;
4529            refuse_in_guest_policy(backend, policy_refusal)?;
4530            settled?;
4531            refuse_in_guest_trap_patching(backend, patched)?;
4532            return Ok(exit_status);
4533        }
4534        #[cfg(not(feature = "liteinst"))]
4535        {
4536            backend.ensure_available()?;
4537            unreachable!("LiteInst availability must fail when the feature is disabled");
4538        }
4539    }
4540    ensure_backend_dispatch(backend)?;
4541
4542    let stats_request = backend_stats::request(print_summary_to_json_file);
4543    let control = control
4544        .ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
4545    // A sequentialized guest tells gdbserver not to serialize its threads;
4546    // see hermit_run_ptrace::spawn_tracer.
4547    let tracer = hermit_run_ptrace::spawn_tracer(
4548        command,
4549        config.clone(),
4550        config.gdbserver.then_some(config.gdbserver_port),
4551        config.sequentialize_threads,
4552        stats_request,
4553    )
4554    .await?;
4555    let stats_source = tracer.backend_stats();
4556    let (exit_status, global_state) = ptrace_completion::wait(tracer, control).await?;
4557    let dispatch_stats =
4558        backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
4559    global_state
4560        .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
4561        .await; // Before it's dropped by this function.
4562    Ok(exit_status)
4563}
4564
4565/// Variant of `run` that also captures stdout/stderr.
4566///
4567/// On ptrace it needs no particular stack from the calling thread; see [`run`].
4568pub fn run_with_output(
4569    command: Command,
4570    config: DetConfig,
4571    print_summary: bool,
4572    print_summary_to_json_file: &Option<PathBuf>,
4573) -> Result<Output, Error> {
4574    run_with_output_backend(
4575        command,
4576        config,
4577        print_summary,
4578        print_summary_to_json_file,
4579        Backend::Ptrace,
4580    )
4581}
4582
4583/// Variant of [`run_with_backend`] that also captures stdout/stderr.
4584///
4585/// On ptrace it needs no particular stack from the calling thread; see [`run`].
4586pub fn run_with_output_backend(
4587    command: Command,
4588    config: DetConfig,
4589    print_summary: bool,
4590    print_summary_to_json_file: &Option<PathBuf>,
4591    backend: Backend,
4592) -> Result<Output, Error> {
4593    if backend == Backend::Kvm {
4594        ensure_kvm_stdin_reserved()?;
4595    }
4596    run_with_output_backend_timeout(
4597        command,
4598        config,
4599        print_summary,
4600        print_summary_to_json_file,
4601        backend,
4602        None,
4603    )
4604}
4605
4606/// [`run_with_output_backend`] with a hermit-enforced wall-clock bound.
4607///
4608/// See [`run_with_backend_timeout`]; the teardown semantics are identical. On
4609/// ptrace it needs no particular stack from the calling thread; see [`run`].
4610pub fn run_with_output_backend_timeout(
4611    command: Command,
4612    config: DetConfig,
4613    print_summary: bool,
4614    print_summary_to_json_file: &Option<PathBuf>,
4615    backend: Backend,
4616    timeout: Option<Duration>,
4617) -> Result<Output, Error> {
4618    if backend == Backend::Ptrace {
4619        let summary_path = print_summary_to_json_file.clone();
4620        let command = tracer_thread::SendCommand::new(command);
4621        return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4622            let command = command.into_inner();
4623            let report = SkidOvershootReport::begin(true);
4624            // Box before the retained operation captures the backend state;
4625            // constructing and polling it still happen after admission here.
4626            let result = Box::pin(dispatch_output_backend(
4627                command,
4628                prepare_backend_config(config, backend),
4629                print_summary,
4630                &summary_path,
4631                backend,
4632                Some(control),
4633            ))
4634            .await;
4635            report.finish(result)
4636        });
4637    }
4638    let (output, skid_overshoots) = run_with_output_backend_timeout_and_skid_overshoots(
4639        command,
4640        config,
4641        print_summary,
4642        print_summary_to_json_file,
4643        backend,
4644        timeout,
4645    )?;
4646    if skid_overshoots > 0 {
4647        return Err(Error::new(SkidOvershootError::new(skid_overshoots)));
4648    }
4649    Ok(output)
4650}
4651
4652/// Run with captured output and return the number of precise PMU timer
4653/// overshoots alongside it instead of refusing before a caller can inspect the
4654/// completed output. The `--verify` path uses this to finish and publish its
4655/// comparison before it refuses the overshoot-tainted result.
4656#[doc(hidden)]
4657pub fn run_with_output_backend_timeout_and_skid_overshoots(
4658    command: Command,
4659    config: DetConfig,
4660    print_summary: bool,
4661    print_summary_to_json_file: &Option<PathBuf>,
4662    backend: Backend,
4663    timeout: Option<Duration>,
4664) -> Result<(Output, u64), Error> {
4665    if backend == Backend::Ptrace {
4666        let summary_path = print_summary_to_json_file.clone();
4667        let command = tracer_thread::SendCommand::new(command);
4668        return ptrace_completion::run_on_tracer_thread(timeout, move |control| async move {
4669            let command = command.into_inner();
4670            let report = SkidOvershootReport::begin(true);
4671            let result = Box::pin(dispatch_output_backend(
4672                command,
4673                prepare_backend_config(config, backend),
4674                print_summary,
4675                &summary_path,
4676                backend,
4677                Some(control),
4678            ))
4679            .await;
4680            report.finish_with_count(result)
4681        });
4682    }
4683    let skid_overshoot_report = SkidOvershootReport::begin(backend.uses_ptrace_pmu_timers());
4684    if backend == Backend::Kvm {
4685        // Reserve before the Tokio runtime can reuse a closed fd 0. KVM
4686        // verification consumes the explicit output snapshot in `run_kvm`;
4687        // public output-capture callers without one retain this reservation.
4688        ensure_kvm_stdin_reserved()?;
4689    }
4690    let config = prepare_backend_config(config, backend);
4691    let result = run_with_output_backend_inner(
4692        command,
4693        config,
4694        print_summary,
4695        print_summary_to_json_file,
4696        backend,
4697        timeout,
4698    );
4699    skid_overshoot_report.finish_with_count(result)
4700}
4701
4702#[tokio::main(flavor = "current_thread")]
4703async fn run_with_output_backend_inner(
4704    command: Command,
4705    config: DetConfig,
4706    print_summary: bool,
4707    print_summary_to_json_file: &Option<PathBuf>,
4708    backend: Backend,
4709    timeout: Option<Duration>,
4710) -> Result<Output, Error> {
4711    refuse_in_guest_liteinst_timeout(backend, timeout)?;
4712    // Keep the backend state off the caller's stack before Tokio and the
4713    // deadline future capture it. Polling and teardown stay on this thread.
4714    let guest = Box::pin(dispatch_output_backend(
4715        command,
4716        config,
4717        print_summary,
4718        print_summary_to_json_file,
4719        backend,
4720        None,
4721    ));
4722    match timeout {
4723        None => guest.await,
4724        Some(limit) => match tokio::time::timeout(limit, guest).await {
4725            Ok(result) => result,
4726            Err(_elapsed) => Err(Error::new(GuestTimedOut { limit })),
4727        },
4728    }
4729}
4730
4731async fn dispatch_output_backend(
4732    mut command: Command,
4733    mut config: DetConfig,
4734    print_summary: bool,
4735    print_summary_to_json_file: &Option<PathBuf>,
4736    backend: Backend,
4737    control: Option<std::rc::Rc<ptrace_completion::Control>>,
4738) -> Result<Output, Error> {
4739    // Every launch path, ptrace's included, reaches the guest through here.
4740    crate::cpu_profile_admission::refuse_unadmitted_launch(&config, backend == Backend::Ptrace)?;
4741    config.launch_image = launched_image(&command);
4742    if backend == Backend::Kvm {
4743        return run_kvm(
4744            &command,
4745            config,
4746            print_summary,
4747            print_summary_to_json_file,
4748            true,
4749        )
4750        .await;
4751    }
4752    if backend == Backend::Dbt {
4753        #[cfg(feature = "dbt")]
4754        {
4755            return run_dbt(command, config, print_summary, true).await;
4756        }
4757        #[cfg(not(feature = "dbt"))]
4758        {
4759            backend.ensure_available()?;
4760            unreachable!("DBT availability must fail when the feature is disabled");
4761        }
4762    }
4763    if backend == Backend::Sabre {
4764        #[cfg(not(feature = "sabre"))]
4765        backend.ensure_available()?;
4766        command.stdin(output_backend_stdin()?);
4767        command.stdout(Stdio::piped());
4768        command.stderr(Stdio::piped());
4769        return run_sabre(
4770            command,
4771            config,
4772            print_summary,
4773            print_summary_to_json_file,
4774            true,
4775        )
4776        .await;
4777    }
4778    if backend.is_in_guest_liteinst() {
4779        #[cfg(feature = "liteinst")]
4780        {
4781            command.stdin(output_backend_stdin()?);
4782            let stats_request = in_guest_stats_request(backend, print_summary_to_json_file);
4783            refuse_in_guest_liteinst_run(&mut command, &config, backend)?;
4784            let (launch, _detlog_descriptor) =
4785                in_guest_liteinst_launch(&mut command, &in_guest_detlog_forward_policy())?;
4786            let tool_data = launch.encode();
4787            // Every Tool image must forward on that socket, by that policy;
4788            // see detcore::Config::in_guest_detlog_forward_policy.
4789            let mut config = config;
4790            config.in_guest_detlog_forward_policy = _detlog_descriptor
4791                .is_some()
4792                .then(|| in_guest_detlog_forward_policy().encode());
4793            config.in_guest_site_patching_off = in_guest_site_patching_off(backend);
4794            let preload = liteinst_tool_runtime_library_path()?;
4795            let exits = std::sync::Arc::new(in_guest_exits::InGuestExitAdmission::default());
4796            let (output, mut global_state, dispatch_stats, process_reports) =
4797                reverie_liteinst::LiteinstBackend::with_connection_admission(exits.clone(), async {
4798                    if stats_request.is_enabled() {
4799                        let (output, global_state, source) =
4800                            reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data_and_stats::<
4801                                Detcore,
4802                            >(command, config, preload, tool_data)
4803                            .await?;
4804                        let dispatch_stats = backend_stats::report(backend, stats_request, &source);
4805                        let process_reports = source.snapshot().process_reports();
4806                        Ok::<_, reverie::Error>((output, global_state, dispatch_stats, process_reports))
4807                    } else {
4808                        let (output, global_state) =
4809                            reverie_liteinst::LiteinstBackend::run_with_output_and_preload_data::<
4810                                Detcore,
4811                            >(command, config, preload, tool_data)
4812                            .await?;
4813                        Ok((output, global_state, None, 0))
4814                    }
4815                })
4816                .await
4817                .inspect_err(|error| exits.fail_launch(error))?;
4818            let patched =
4819                in_guest_trap_patching_evidence(backend, dispatch_stats.as_ref(), process_reports);
4820            let settled = settle_in_guest_exits(&exits, &global_state).await;
4821            let policy_refusal = global_state.policy_refusal();
4822            let output = Output {
4823                status: output.status.into(),
4824                stdout: output.stdout,
4825                stderr: output.stderr,
4826            };
4827            let status = output.status;
4828            if settled.is_err() || liteinst_requires_forced_shutdown(status) {
4829                global_state.force_shutdown_with_error();
4830                global_state.cancel_internal_scheduler().await;
4831            }
4832            global_state
4833                .clean_up_with_dispatch_stats(
4834                    print_summary,
4835                    print_summary_to_json_file,
4836                    dispatch_stats,
4837                )
4838                .await;
4839            refuse_in_guest_policy(backend, policy_refusal)?;
4840            settled?;
4841            refuse_in_guest_trap_patching(backend, patched)?;
4842            return Ok(Output {
4843                status,
4844                stdout: output.stdout,
4845                stderr: output.stderr,
4846            });
4847        }
4848        #[cfg(not(feature = "liteinst"))]
4849        {
4850            backend.ensure_available()?;
4851            unreachable!("LiteInst availability must fail when the feature is disabled");
4852        }
4853    }
4854    ensure_backend_dispatch(backend)?;
4855
4856    let stats_request = backend_stats::request(print_summary_to_json_file);
4857    command.stdin(output_backend_stdin()?);
4858    command.stdout(Stdio::piped());
4859    command.stderr(Stdio::piped());
4860    let control = control
4861        .ok_or_else(|| Error::msg("ordinary ptrace requires its retained operation owner"))?;
4862    // A sequentialized guest tells gdbserver not to serialize its threads;
4863    // see hermit_run_ptrace::spawn_tracer.
4864    let tracer = hermit_run_ptrace::spawn_tracer(
4865        command,
4866        config.clone(),
4867        config.gdbserver.then_some(config.gdbserver_port),
4868        config.sequentialize_threads,
4869        stats_request,
4870    )
4871    .await?;
4872    let stats_source = tracer.backend_stats();
4873    let (output, global_state) = ptrace_completion::wait_with_output(tracer, control).await?;
4874    let dispatch_stats =
4875        backend_stats::report_if_collected(backend, stats_request, stats_source.as_ref());
4876    global_state
4877        .clean_up_with_dispatch_stats(print_summary, print_summary_to_json_file, dispatch_stats)
4878        .await;
4879    Ok(output)
4880}
4881
4882/// Holds the context necessary to run high-level hermit functions.
4883pub struct HermitData {
4884    // The data directory. Defaults to `~/.cache/hermit`. Note that we shouldn't
4885    // expect this to exist in any of the functions that are called.
4886    data_dir: PathBuf,
4887}
4888
4889fn collect_recording_ids(
4890    entries: impl IntoIterator<Item = io::Result<fs::DirEntry>>,
4891    data_dir: &Path,
4892    mut file_type: impl FnMut(&fs::DirEntry) -> io::Result<fs::FileType>,
4893) -> Result<Vec<Id>, Error> {
4894    let mut recordings = Vec::new();
4895    for entry in entries {
4896        let entry = entry.with_context(|| {
4897            format!(
4898                "Failed to read an entry in recording inventory {}",
4899                data_dir.display()
4900            )
4901        })?;
4902        let path = entry.path();
4903        if file_type(&entry)
4904            .with_context(|| {
4905                format!(
4906                    "Failed to inspect recording inventory entry {}",
4907                    path.display()
4908                )
4909            })?
4910            .is_dir()
4911            && let Some(id) = entry
4912                .file_name()
4913                .to_str()
4914                .and_then(|name| name.parse::<Id>().ok())
4915        {
4916            recordings.push(id);
4917        }
4918    }
4919    Ok(recordings)
4920}
4921
4922impl Default for HermitData {
4923    fn default() -> Self {
4924        Self::new()
4925    }
4926}
4927
4928impl HermitData {
4929    /// Creates an instance of `HermitData` using `~/.cache/hermit` as the data
4930    /// directory.
4931    pub fn new() -> Self {
4932        Self::with_dir(
4933            dirs::cache_dir()
4934                .map_or_else(|| PathBuf::from("/tmp/hermit"), |dir| dir.join("hermit")),
4935        )
4936    }
4937
4938    /// Creates a `HermitData` using the given directory as the base path for
4939    /// storing recording data.
4940    pub fn with_dir<P>(data_dir: P) -> Self
4941    where
4942        P: Into<PathBuf>,
4943    {
4944        Self {
4945            data_dir: data_dir.into(),
4946        }
4947    }
4948
4949    /// Returns the path to the data directory where recordings are stored.
4950    pub fn data_dir(&self) -> &Path {
4951        &self.data_dir
4952    }
4953
4954    /// Records the execution of the given command, returning its `Recording`.
4955    ///
4956    /// If recording failed, then an error is returned. Note that if the command
4957    /// itself failed, then we still return a successful recording, but its exit
4958    /// status will be non-zero.
4959    ///
4960    /// This low-level API does not create a Hermit container, so it has no
4961    /// authenticated private-mount provenance to supply. Detcore derives mount
4962    /// identities from the completed guest namespace. CLI container callers
4963    /// with producer-owned root provenance must use
4964    /// [`Self::record_with_mountinfo`].
4965    ///
4966    /// The ptrace session runs on a tracer thread, so the calling thread needs no
4967    /// particular stack; see [`run`].
4968    pub fn record(&self, command: Command) -> Result<Recording, Error> {
4969        let store = Self {
4970            data_dir: self.data_dir.clone(),
4971        };
4972        let command = tracer_thread::SendCommand::new(command);
4973        ptrace_completion::run_on_tracer_thread(None, move |control| async move {
4974            let command = command.into_inner();
4975            let data = store.create_recording_dir()?;
4976            let exit_status = record_to_async(
4977                command,
4978                data.path(),
4979                MountProvenance::default(),
4980                None,
4981                None,
4982                None,
4983                detcore_model::cpu_profile::CpuProfile::default(),
4984                control,
4985            )
4986            .await?;
4987            store.commit_recording(data, exit_status)
4988        })
4989    }
4990
4991    /// Records with mountinfo provenance captured from the active container.
4992    ///
4993    /// The ptrace session runs on a tracer thread, so the calling thread needs no
4994    /// particular stack; see [`run`].
4995    pub fn record_with_mountinfo(
4996        &self,
4997        command: Command,
4998        mountinfo_root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
4999    ) -> Result<Recording, Error> {
5000        let store = Self {
5001            data_dir: self.data_dir.clone(),
5002        };
5003        let command = tracer_thread::SendCommand::new(command);
5004        ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5005            let command = command.into_inner();
5006            let data = store.create_recording_dir()?;
5007            let mount_ids = capture_mountinfo_identity_order()?;
5008            let exit_status = record_to_async(
5009                command,
5010                data.path(),
5011                MountProvenance {
5012                    root_rewrites: mountinfo_root_rewrites,
5013                    container_mount_table: None,
5014                    mount_ids: None,
5015                },
5016                Some(mount_ids),
5017                None,
5018                None,
5019                detcore_model::cpu_profile::CpuProfile::default(),
5020                control,
5021            )
5022            .await?;
5023            store.commit_recording(data, exit_status)
5024        })
5025    }
5026
5027    /// Creates a temporary directory for a recording that has not been committed yet.
5028    pub fn create_recording_dir(&self) -> Result<tempfile::TempDir, Error> {
5029        let tmp_data_dir = self.data_dir.join("tmp");
5030
5031        fs::create_dir_all(&tmp_data_dir).with_context(|| {
5032            format!(
5033                "Failed to create recording directory: {}",
5034                self.data_dir.display()
5035            )
5036        })?;
5037
5038        Ok(tempfile::TempDir::new_in(tmp_data_dir)?)
5039    }
5040
5041    /// Commits a completed temporary recording to the recording store.
5042    pub fn commit_recording(
5043        &self,
5044        data: tempfile::TempDir,
5045        exit_status: ExitStatus,
5046    ) -> Result<Recording, Error> {
5047        let id = Id::unique();
5048
5049        // Atomically move the temporary recording to its final location.
5050        fs::rename(data.keep(), self.data_dir.join(id.to_string()))?;
5051
5052        self.note_latest(&id, true)
5053            .with_context(|| format!("Failed to update {:?}", self.data_dir.join(LAST)))?;
5054
5055        Ok(Recording { id, exit_status })
5056    }
5057
5058    /// Replays the given recording ID.
5059    ///
5060    /// The ptrace session runs on a tracer thread, so the calling thread needs no
5061    /// particular stack; see [`run`].
5062    pub fn replay(&self, id: Id) -> Result<ExitStatus, Error> {
5063        let data = self.data_dir.join(id.to_string());
5064        replay_from(&data)
5065    }
5066
5067    /// Replays the given recording ID with a gdbserver available to attach to.
5068    ///
5069    /// The ptrace session runs on a tracer thread, so the calling thread needs no
5070    /// particular stack; see [`run`].
5071    pub fn replay_with_gdbserver(&self, id: Id, port: u16) -> Result<ExitStatus, Error> {
5072        let data = self.data_dir.join(id.to_string());
5073        replay_with_gdbserver(&data, port)
5074    }
5075
5076    /// Returns an iterator over the recordings.
5077    ///
5078    /// Use [`Self::recording_metadata`] to get more information about a recording.
5079    pub fn recordings(&self) -> impl Iterator<Item = Id> + use<> {
5080        fs::read_dir(&self.data_dir)
5081            .ok()
5082            .into_iter()
5083            .flatten()
5084            .filter_map(|entry| {
5085                let entry = entry.ok()?;
5086
5087                if entry.file_type().ok()?.is_dir() {
5088                    Some(entry.file_name().to_str()?.parse::<Id>().ok()?)
5089                } else {
5090                    None
5091                }
5092            })
5093    }
5094
5095    /// Returns all recordings, or an error if the data directory cannot be
5096    /// enumerated completely.
5097    ///
5098    /// A missing data directory has no recordings. Other filesystem errors are
5099    /// returned rather than being mistaken for an empty or partial inventory.
5100    pub fn try_recordings(&self) -> Result<Vec<Id>, Error> {
5101        let entries = match fs::read_dir(&self.data_dir) {
5102            Ok(entries) => entries,
5103            Err(error) if error.kind() == io::ErrorKind::NotFound => return Ok(Vec::new()),
5104            Err(error) => {
5105                return Err(error).with_context(|| {
5106                    format!(
5107                        "Failed to read recording inventory in {}",
5108                        self.data_dir.display()
5109                    )
5110                });
5111            }
5112        };
5113
5114        collect_recording_ids(entries, &self.data_dir, fs::DirEntry::file_type)
5115    }
5116
5117    /// Returns the metadata of a recording.
5118    pub fn recording_metadata(&self, id: Id) -> Result<Metadata, Error> {
5119        Metadata::load(&self.data_dir.join(id.to_string()))
5120    }
5121
5122    /// Deletes a recording.
5123    pub fn remove(&self, id: Id) -> Result<(), Error> {
5124        let path = self.data_dir.join(id.to_string());
5125
5126        // Before deleting anything, make sure this file exists. This may not be a
5127        // recording if this file does not exist. A run manifest marks a
5128        // recording too: a run that drew an input from the host leaves only
5129        // that (https://github.com/rrnewton/hermit/issues/4271).
5130        let metadata_path = [METADATA_NAME, RUN_MANIFEST_NAME]
5131            .into_iter()
5132            .map(|name| path.join(name))
5133            .find(|marker| marker.exists())
5134            .unwrap_or_else(|| path.join(METADATA_NAME));
5135        let metadata = fs::metadata(&metadata_path)
5136            .with_context(|| format!("Failed to find {:?}", metadata_path))?;
5137
5138        if !metadata.is_file() {
5139            return Err(anyhow!("{:?} is not a file", metadata_path));
5140        }
5141
5142        // Do a recursive delete on the directory. Note that this does not follow
5143        // symlinks.
5144        fs::remove_dir_all(path)?;
5145
5146        Ok(())
5147    }
5148
5149    /// Returns the last recorded ID.
5150    pub fn last_id(&self) -> Result<Id, Error> {
5151        Ok(fs::read_to_string(self.data_dir.join(LAST))?.parse()?)
5152    }
5153
5154    /// Atomically names `id` as the newest recording: `last-run` always,
5155    /// and `last`, which a bare `hermit replay` replays, when the user
5156    /// `asked` for the recording (`hermit record`, `hermit run
5157    /// --record-networking`) rather than a run leaving its manifest; see
5158    /// <https://github.com/rrnewton/hermit/issues/4271>.
5159    pub fn note_latest(&self, id: &Id, asked: bool) -> Result<(), Error> {
5160        let tmp = self.data_dir.join("tmp");
5161        fs::create_dir_all(&tmp)?;
5162        let names = if asked {
5163            &[LAST_RUN, LAST][..]
5164        } else {
5165            &[LAST_RUN][..]
5166        };
5167        for name in names {
5168            let mut file = tempfile::NamedTempFile::new_in(&tmp)?;
5169            write!(file, "{}", id)?;
5170            file.persist(self.data_dir.join(name))?;
5171        }
5172        Ok(())
5173    }
5174}
5175
5176/// What a recording takes from the completed recording container's mount
5177/// namespace, which a caller without a Hermit container leaves empty.
5178#[derive(Clone, Debug, Default)]
5179pub struct MountProvenance {
5180    /// The proven roots of Hermit's own mounts
5181    /// (`detcore::Config::mountinfo_root_rewrites`).
5182    pub root_rewrites: Vec<detcore_model::config::MountInfoRootRewrite>,
5183    /// The guest's container mount table
5184    /// (`detcore::Config::container_mount_table`), which the recording carries
5185    /// for its replay.
5186    pub container_mount_table: Option<detcore_model::container_mounts::ContainerMountTable>,
5187    /// The namespace's identity order, read with the table
5188    /// (`detcore::Config::mountinfo_mount_ids`). `None` asks the recorder to
5189    /// capture it. A table and an order from two reads need not agree: a host
5190    /// process that removes a host mount's directory detaches the copy of that
5191    /// mount from the container too, so a row the table shows can be gone
5192    /// from a later read.
5193    pub mount_ids: Option<Vec<u64>>,
5194}
5195
5196/// `NS_GET_MNTNS_ID`, `_IOR(NSIO, 5, __u64)` in Linux's uapi/linux/nsfs.h.
5197const NS_GET_MNTNS_ID: libc::c_ulong = (2 << 30) | (8 << 16) | (0xb7 << 8) | 5;
5198
5199/// The calling thread's mount namespace (`DetConfig::mountinfo_mount_namespace`):
5200/// the kernel's namespace ID from `ioctl(NS_GET_MNTNS_ID)` on
5201/// `/proc/thread-self/ns/mnt`, and the descriptor's device and inode numbers.
5202/// The calling thread's, not the thread group leader's: a library caller's
5203/// thread can have a mount namespace of its own, and every capture here
5204/// (`/proc/thread-self/mountinfo` and `fdinfo`) reads that same thread's. A
5205/// kernel without the ioctl (ENOTTY or EINVAL) yields no ID; any other failure
5206/// is an error.
5207pub fn current_mount_namespace() -> Result<detcore_model::config::MountNamespaceIdentity, Error> {
5208    use std::os::fd::AsRawFd;
5209    use std::os::unix::fs::MetadataExt;
5210    let file = fs::File::open("/proc/thread-self/ns/mnt")
5211        .context("failed to open this thread's mount namespace")?;
5212    let metadata = file
5213        .metadata()
5214        .context("failed to read this process's mount namespace")?;
5215    let mut id: u64 = 0;
5216    // SAFETY: NS_GET_MNTNS_ID writes one u64 through the pointer, which
5217    // points at `id` for the duration of the call.
5218    let id =
5219        if unsafe { libc::ioctl(file.as_raw_fd(), NS_GET_MNTNS_ID, &mut id as *mut u64) } == 0 {
5220            Some(id)
5221        } else {
5222            let error = std::io::Error::last_os_error();
5223            match error.raw_os_error() {
5224                Some(libc::ENOTTY | libc::EINVAL) => None,
5225                _ => {
5226                    return Err(Error::new(error)
5227                        .context("failed to read this process's mount namespace ID"));
5228                }
5229            }
5230        };
5231    Ok(detcore_model::config::MountNamespaceIdentity {
5232        id,
5233        device: metadata.dev(),
5234        inode: metadata.ino(),
5235    })
5236}
5237
5238/// The calling thread's mount table (`/proc/thread-self/mountinfo`): the rows
5239/// of the namespace [`current_mount_namespace`] names.
5240pub fn thread_mountinfo() -> Result<Vec<u8>, Error> {
5241    fs::read("/proc/thread-self/mountinfo")
5242        .context("Failed to read this thread's mount table (/proc/thread-self/mountinfo)")
5243}
5244
5245/// The raw mount ID of the mount `path` reaches in the calling thread's
5246/// namespace, from the `fdinfo` of an `O_PATH` descriptor held on it; `None`
5247/// where it cannot be opened. O_PATH pins the object without read
5248/// permission.
5249fn thread_mount_id_of(path: &Path) -> Option<u64> {
5250    held_mount_id(&hold_path(path, false).ok()?)
5251}
5252
5253/// An `O_PATH` descriptor held on `path` (a directory, with `directory`),
5254/// resolved as `chdir` and `open` resolve it: following symbolic links, and
5255/// a relative path from the calling thread's working directory, whose name is
5256/// never asked for. Holding it pins the mount it reaches, and the lookup has
5257/// already triggered any automount on the way.
5258fn hold_path(path: &Path, directory: bool) -> nix::Result<std::os::fd::OwnedFd> {
5259    use nix::fcntl::OFlag;
5260    let flags = OFlag::O_PATH
5261        | OFlag::O_CLOEXEC
5262        | if directory {
5263            OFlag::O_DIRECTORY
5264        } else {
5265            OFlag::empty()
5266        };
5267    nix::fcntl::open(path, flags, nix::sys::stat::Mode::empty())
5268}
5269
5270/// The raw mount ID of the mount `held` reaches, from its
5271/// `/proc/thread-self/fdinfo`.
5272fn held_mount_id(held: &std::os::fd::OwnedFd) -> Option<u64> {
5273    let fdinfo = fs::read(format!("/proc/thread-self/fdinfo/{}", held.as_raw_fd())).ok()?;
5274    detcore_model::procfs::parse_fdinfo_mount_id(&fdinfo)
5275}
5276
5277/// Capture the calling thread's mount namespace's raw IDs in the exact
5278/// row/parent order used by Detcore's canonical mountinfo mapping.
5279pub fn capture_mountinfo_identity_order() -> Result<Vec<u64>, Error> {
5280    mountinfo_identity_order_from_raw(&thread_mountinfo()?)
5281}
5282
5283/// [`capture_mountinfo_identity_order`], keeping every row whose mount ID is
5284/// in `keep` (the rows a container mount table shows) whatever its name: a
5285/// mount Hermit installed is never dropped by the seed filter, so a table
5286/// showing it validates against the captured order.
5287pub fn capture_mountinfo_identity_order_keeping(
5288    keep: &std::collections::BTreeSet<u64>,
5289) -> Result<Vec<u64>, Error> {
5290    mountinfo_identity_order_keeping_from_raw(&thread_mountinfo()?, keep)
5291}
5292
5293/// Each of [`BASE_MOUNTPOINTS`](detcore_model::container_mounts::BASE_MOUNTPOINTS)
5294/// that the calling thread can open, as the kernel escapes it in `mountinfo`,
5295/// with the mount ID of a descriptor held on it: rule 2's proof of
5296/// `ContainerMountTable::select`. The base mountpoints hold no byte the kernel
5297/// escapes (space, tab, newline or backslash), so each is its own escaped form.
5298pub fn base_mountpoint_mount_ids() -> Vec<(Vec<u8>, u64)> {
5299    detcore_model::container_mounts::BASE_MOUNTPOINTS
5300        .iter()
5301        .filter_map(|mountpoint| {
5302            let id = thread_mount_id_of(Path::new(mountpoint))?;
5303            Some((mountpoint.as_bytes().to_vec(), id))
5304        })
5305        .collect()
5306}
5307
5308/// A container mount table and the raw identity order Detcore validates it
5309/// against ([`unplanned_container_mount_table`]).
5310pub type UnplannedMountTable = (
5311    detcore_model::container_mounts::ContainerMountTable,
5312    Vec<u64>,
5313);
5314
5315// TODO-HUMAN-REVIEW(https://github.com/rrnewton/hermit/issues/4213): Review
5316// the container mount table of a run in a namespace Hermit did not make: the
5317// membership rule of K3a with the launch mounts in place of Hermit's
5318// installations.
5319/// The container mount table of a run whose guest runs in the calling
5320/// thread's own mount namespace, in which Hermit installed no mount
5321/// (`--no-namespace`, or a library caller that built no container, on KVM),
5322/// and the raw identity order Detcore validates it against, both from one
5323/// read of the namespace's rows. Shown are:
5324/// - the launch mounts: the mount holding `launch_cwd`, the guest's working
5325///   directory at launch, and the mount holding the host's `/tmp`, which the
5326///   guest shares, with their ancestors (rules 1 and 3 of
5327///   `ContainerMountTable::select`, as for Hermit's installations), so that
5328///   `df .` and `findmnt -T .` from a checkout find their row;
5329/// - the base mountpoints mounted here (rule 2).
5330///
5331/// Both are facts of the launch, fixed before the guest starts, as the base
5332/// mountpoints are. No other host mount is shown; a file on one reports its
5333/// nearest shown ancestor. A shown row's parent is its nearest shown
5334/// ancestor, as for every table.
5335///
5336/// `launch_cwd` may be relative (`.` for the inherited working directory):
5337/// it is resolved from the calling thread's working directory as the guest's
5338/// `chdir` will resolve it, without asking that directory for its name, so a
5339/// removed working directory does not stop a launch with an absolute
5340/// `--workdir`.
5341pub fn unplanned_container_mount_table(launch_cwd: &Path) -> Result<UnplannedMountTable, Error> {
5342    unplanned_container_mount_table_with(launch_cwd, thread_mountinfo)
5343}
5344
5345/// [`unplanned_container_mount_table`], reading the mount table with `read`.
5346/// The launch directories and the base mountpoints are resolved and held
5347/// first, then the table is read, then the mount IDs are taken from the held
5348/// descriptors: a mount that resolving a launch directory creates (an
5349/// automount on its path) is already in the rows read, and one that leaves
5350/// afterwards is still named by them. A launch mount the read does not list
5351/// is refused, never dropped.
5352fn unplanned_container_mount_table_with(
5353    launch_cwd: &Path,
5354    read: impl FnOnce() -> Result<Vec<u8>, Error>,
5355) -> Result<UnplannedMountTable, Error> {
5356    let working = hold_path(launch_cwd, true).with_context(|| {
5357        format!(
5358            "the guest's working directory {} cannot be opened for its mount table",
5359            launch_cwd.display()
5360        )
5361    })?;
5362    // The host /tmp, which the guest shares, if there is one.
5363    let tmp = hold_path(Path::new("/tmp"), true).ok();
5364    let base = detcore_model::container_mounts::BASE_MOUNTPOINTS
5365        .iter()
5366        .filter_map(|mountpoint| Some((*mountpoint, hold_path(Path::new(mountpoint), false).ok()?)))
5367        .collect::<Vec<_>>();
5368    let raw = read()?;
5369    let launch = std::iter::once(&working)
5370        .chain(tmp.as_ref())
5371        .map(|held| {
5372            held_mount_id(held)
5373                .ok_or_else(|| anyhow!("a launch directory's mount ID cannot be read"))
5374        })
5375        .collect::<Result<std::collections::BTreeSet<_>, Error>>()?;
5376    let base = base
5377        .iter()
5378        .filter_map(|(mountpoint, held)| {
5379            Some((mountpoint.as_bytes().to_vec(), held_mount_id(held)?))
5380        })
5381        .collect::<Vec<_>>();
5382    unplanned_container_mount_table_from(&raw, &launch, &base)
5383}
5384
5385fn unplanned_container_mount_table_from(
5386    raw: &[u8],
5387    launch: &std::collections::BTreeSet<u64>,
5388    base: &[(Vec<u8>, u64)],
5389) -> Result<UnplannedMountTable, Error> {
5390    use detcore_model::container_mounts::ContainerMountTable;
5391    let rows = detcore_model::container_mounts::parse_container_mounts(raw)
5392        .ok_or_else(|| anyhow!("this thread's mount table has a malformed row"))?;
5393    if let Some(missing) = launch
5394        .iter()
5395        .find(|id| !rows.iter().any(|row| row.raw_mount_id == **id))
5396    {
5397        anyhow::bail!(
5398            "the launch mount {missing} (holding the guest's working directory or /tmp) is not in \
5399             this thread's mount table, read after it was resolved; refusing a table that would \
5400             omit the mount the guest starts on"
5401        );
5402    }
5403    let never = rows
5404        .iter()
5405        .filter(|row| row.is_ephemeral_host_seed())
5406        .map(|row| row.raw_mount_id)
5407        .collect();
5408    let table = ContainerMountTable::select(&rows, launch, base, &never);
5409    let order = mountinfo_identity_order_keeping_from_raw(raw, &table.shown_mount_ids())?;
5410    Ok((table, order))
5411}
5412
5413/// Producer provenance follows the guest mount model: ephemeral host seed rows
5414/// (other processes' squashfuse mounts) are not namespace members and must not
5415/// enter the captured identity order. Detcore drops the same rows with the same
5416/// filter when it captures the guest's mountinfo.
5417fn mountinfo_identity_order_from_raw(raw: &[u8]) -> Result<Vec<u64>, Error> {
5418    mountinfo_identity_order_keeping_from_raw(raw, &std::collections::BTreeSet::new())
5419}
5420
5421/// The identity order of the mountinfo contents `raw` (seed rows dropped, as
5422/// `mountinfo_identity_order_from_raw` drops them), keeping a seed row whose
5423/// mount ID is in `keep`.
5424pub fn mountinfo_identity_order_keeping_from_raw(
5425    raw: &[u8],
5426    keep: &std::collections::BTreeSet<u64>,
5427) -> Result<Vec<u64>, Error> {
5428    let mut kept = Vec::with_capacity(raw.len());
5429    for line in raw.split_inclusive(|byte| *byte == b'\n') {
5430        let body = line.strip_suffix(b"\n").unwrap_or(line);
5431        let id = body
5432            .split(|byte| *byte == b' ')
5433            .next()
5434            .and_then(|field| std::str::from_utf8(field).ok()?.parse::<u64>().ok());
5435        if !detcore_model::procfs::is_ephemeral_host_seed_mount(body)
5436            || id.is_some_and(|id| keep.contains(&id))
5437        {
5438            kept.extend_from_slice(line);
5439        }
5440    }
5441    mountinfo_identity_order_from(&kept)
5442}
5443
5444fn mountinfo_identity_order_from(contents: &[u8]) -> Result<Vec<u64>, Error> {
5445    use std::collections::BTreeSet;
5446
5447    let rows = detcore_model::procfs::parse_mountinfo(contents)
5448        .ok_or_else(|| anyhow!("malformed mountinfo"))?;
5449    let mut visible = Vec::new();
5450    let mut parents = Vec::new();
5451    let mut seen = BTreeSet::new();
5452    for row in rows {
5453        seen.insert(row.raw_mount_id);
5454        visible.push(row.raw_mount_id);
5455        parents.push(row.raw_parent_id);
5456    }
5457    for parent in parents {
5458        if seen.insert(parent) {
5459            visible.push(parent);
5460        }
5461    }
5462    Ok(visible)
5463}
5464
5465impl<'a> From<Option<&'a PathBuf>> for HermitData {
5466    fn from(data_dir: Option<&'a PathBuf>) -> Self {
5467        data_dir.map_or_else(Self::new, Self::with_dir)
5468    }
5469}
5470
5471/// Records to an existing directory. The caller must keep its backing resources
5472/// alive through any [`HermitCleanupUnconfirmed`] recovery. [`HermitData::record`]
5473/// owns its temporary recording directory inside the retained operation.
5474///
5475/// The ptrace session runs on a tracer thread, so the calling thread needs no
5476/// particular stack; see [`run`].
5477pub fn record_to(command: Command, dir: &Path) -> Result<ExitStatus, Error> {
5478    let dir = dir.to_owned();
5479    let command = tracer_thread::SendCommand::new(command);
5480    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5481        let command = command.into_inner();
5482        record_to_async(
5483            command,
5484            &dir,
5485            MountProvenance::default(),
5486            None,
5487            None,
5488            None,
5489            detcore_model::cpu_profile::CpuProfile::default(),
5490            control,
5491        )
5492        .await
5493    })
5494}
5495
5496/// Records with producer-owned mountinfo provenance. The directory-lifetime
5497/// obligation is the same as [`record_to`]. `local_networking` and
5498/// `proc_level` are stored in the recording's `metadata.json`, and a replay
5499/// uses that network and that `/proc` level.
5500///
5501/// The ptrace session runs on a tracer thread, so the calling thread needs no
5502/// particular stack; see [`run`].
5503pub fn record_to_with_mountinfo(
5504    command: Command,
5505    dir: &Path,
5506    mountinfo: MountProvenance,
5507    local_networking: bool,
5508    proc_level: detcore_model::config::ProcLevel,
5509    cpu_profile: detcore_model::cpu_profile::CpuProfile,
5510) -> Result<ExitStatus, Error> {
5511    let dir = dir.to_owned();
5512    let command = tracer_thread::SendCommand::new(command);
5513    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5514        let command = command.into_inner();
5515        let mut mountinfo = mountinfo;
5516        let mount_ids = match mountinfo.mount_ids.take() {
5517            Some(mount_ids) => mount_ids,
5518            None => capture_mountinfo_identity_order_keeping(
5519                &mountinfo
5520                    .container_mount_table
5521                    .as_ref()
5522                    .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
5523                    .unwrap_or_default(),
5524            )?,
5525        };
5526        record_to_async(
5527            command,
5528            &dir,
5529            mountinfo,
5530            Some(mount_ids),
5531            Some(local_networking),
5532            Some(proc_level),
5533            cpu_profile,
5534            control,
5535        )
5536        .await
5537    })
5538}
5539
5540// Private plumbing: Record::spawn_with_mountinfo's parameters plus the
5541// ptrace completion control.
5542#[allow(clippy::too_many_arguments)]
5543async fn record_to_async(
5544    command: Command,
5545    dir: &Path,
5546    mountinfo: MountProvenance,
5547    mountinfo_mount_ids: Option<Vec<u64>>,
5548    local_networking: Option<bool>,
5549    proc_level: Option<detcore_model::config::ProcLevel>,
5550    cpu_profile: detcore_model::cpu_profile::CpuProfile,
5551    control: std::rc::Rc<ptrace_completion::Control>,
5552) -> Result<ExitStatus, Error> {
5553    let report = SkidOvershootReport::begin(true);
5554    let result = async {
5555        Record::spawn_with_mountinfo(
5556            command,
5557            dir,
5558            mountinfo,
5559            mountinfo_mount_ids,
5560            local_networking,
5561            proc_level,
5562            cpu_profile,
5563        )
5564        .await?
5565        .wait(control)
5566        .await
5567    }
5568    .await;
5569    report.finish(result)
5570}
5571
5572/// Records and captures output. Keep the directory's backing resources alive
5573/// through any cleanup checkpoint, as for [`record_to`].
5574///
5575/// The ptrace session runs on a tracer thread, so the calling thread needs no
5576/// particular stack; see [`run`].
5577pub fn record_with_output(command: Command, dir: &Path) -> Result<Output, Error> {
5578    let dir = dir.to_owned();
5579    let command = tracer_thread::SendCommand::new(command);
5580    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5581        let command = command.into_inner();
5582        record_with_output_async(
5583            command,
5584            &dir,
5585            MountProvenance::default(),
5586            None,
5587            None,
5588            None,
5589            detcore_model::cpu_profile::CpuProfile::default(),
5590            control,
5591        )
5592        .await
5593    })
5594}
5595
5596/// Records with captured output and exact mountinfo provenance.
5597/// `local_networking` and `proc_level` are as for [`record_to_with_mountinfo`].
5598///
5599/// The ptrace session runs on a tracer thread, so the calling thread needs no
5600/// particular stack; see [`run`].
5601pub fn record_with_output_with_mountinfo(
5602    command: Command,
5603    dir: &Path,
5604    mountinfo: MountProvenance,
5605    local_networking: bool,
5606    proc_level: detcore_model::config::ProcLevel,
5607    cpu_profile: detcore_model::cpu_profile::CpuProfile,
5608) -> Result<Output, Error> {
5609    let dir = dir.to_owned();
5610    let command = tracer_thread::SendCommand::new(command);
5611    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5612        let command = command.into_inner();
5613        let mut mountinfo = mountinfo;
5614        let mount_ids = match mountinfo.mount_ids.take() {
5615            Some(mount_ids) => mount_ids,
5616            None => capture_mountinfo_identity_order_keeping(
5617                &mountinfo
5618                    .container_mount_table
5619                    .as_ref()
5620                    .map(detcore_model::container_mounts::ContainerMountTable::shown_mount_ids)
5621                    .unwrap_or_default(),
5622            )?,
5623        };
5624        record_with_output_async(
5625            command,
5626            &dir,
5627            mountinfo,
5628            Some(mount_ids),
5629            Some(local_networking),
5630            Some(proc_level),
5631            cpu_profile,
5632            control,
5633        )
5634        .await
5635    })
5636}
5637
5638// Private plumbing: Record::spawn_with_mountinfo's parameters plus the
5639// ptrace completion control.
5640#[allow(clippy::too_many_arguments)]
5641async fn record_with_output_async(
5642    mut command: Command,
5643    dir: &Path,
5644    mountinfo: MountProvenance,
5645    mountinfo_mount_ids: Option<Vec<u64>>,
5646    local_networking: Option<bool>,
5647    proc_level: Option<detcore_model::config::ProcLevel>,
5648    cpu_profile: detcore_model::cpu_profile::CpuProfile,
5649    control: std::rc::Rc<ptrace_completion::Control>,
5650) -> Result<Output, Error> {
5651    let report = SkidOvershootReport::begin(true);
5652    command.stdin(Stdio::null());
5653    command.stdout(Stdio::piped());
5654    command.stderr(Stdio::piped());
5655    let result = async {
5656        Record::spawn_with_mountinfo(
5657            command,
5658            dir,
5659            mountinfo,
5660            mountinfo_mount_ids,
5661            local_networking,
5662            proc_level,
5663            cpu_profile,
5664        )
5665        .await?
5666        .wait_with_output(control)
5667        .await
5668    }
5669    .await;
5670    report.finish(result)
5671}
5672
5673/// Replays an existing recording. Materialization and chroot guards remain with
5674/// the original runtime through any cleanup checkpoint.
5675///
5676/// The ptrace session runs on a tracer thread, so the calling thread needs no
5677/// particular stack; see [`run`].
5678pub fn replay_from(dir: &Path) -> Result<ExitStatus, Error> {
5679    replay_plain(dir, None, &[])
5680}
5681
5682/// Replays with a gdb server.
5683///
5684/// The ptrace session runs on a tracer thread, so the calling thread needs no
5685/// particular stack; see [`run`].
5686pub fn replay_with_gdbserver(dir: &Path, port: u16) -> Result<ExitStatus, Error> {
5687    replay_plain(dir, Some(port), &[])
5688}
5689
5690/// Replays with a gdb server and mounts inside the replay chroot.
5691///
5692/// The ptrace session runs on a tracer thread, so the calling thread needs no
5693/// particular stack; see [`run`].
5694pub fn replay_with_gdbserver_and_mounts(
5695    dir: &Path,
5696    port: u16,
5697    mounts: &[Mount],
5698) -> Result<ExitStatus, Error> {
5699    replay_plain(dir, Some(port), mounts)
5700}
5701
5702fn replay_plain(dir: &Path, port: Option<u16>, mounts: &[Mount]) -> Result<ExitStatus, Error> {
5703    let dir = dir.to_owned();
5704    let mounts = mounts.to_vec();
5705    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5706        let report = SkidOvershootReport::begin(true);
5707        let result = async {
5708            Replay::spawn(&dir, false, port, &mounts)
5709                .await?
5710                .wait(control)
5711                .await
5712        }
5713        .await;
5714        report.finish(result)
5715    })
5716}
5717
5718/// Replays with captured output.
5719///
5720/// The ptrace session runs on a tracer thread, so the calling thread needs no
5721/// particular stack; see [`run`].
5722pub fn replay_with_output(dir: &Path) -> Result<Output, Error> {
5723    replay_with_output_and_mounts(dir, &[])
5724}
5725
5726/// Replays with captured output and mounts inside the replay chroot.
5727///
5728/// The ptrace session runs on a tracer thread, so the calling thread needs no
5729/// particular stack; see [`run`].
5730pub fn replay_with_output_and_mounts(dir: &Path, mounts: &[Mount]) -> Result<Output, Error> {
5731    let dir = dir.to_owned();
5732    let mounts = mounts.to_vec();
5733    ptrace_completion::run_on_tracer_thread(None, move |control| async move {
5734        let report = SkidOvershootReport::begin(true);
5735        let result = async {
5736            Replay::spawn(&dir, true, None, &mounts)
5737                .await?
5738                .wait_with_output(control)
5739                .await
5740        }
5741        .await;
5742        report.finish(result)
5743    })
5744}
5745
5746#[cfg(test)]
5747mod tests {
5748    use super::*;
5749
5750    static SKID_OVERSHOOT_TEST_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
5751
5752    /// Runs `check_tracing_environment` against probes that report `denied`
5753    /// as unavailable and every other probe as available; returns the refusal,
5754    /// if any, and the probes in the order they ran.
5755    fn check_with_denied(
5756        namespaces: NamespaceUse,
5757        denied: &[CapabilityProbe],
5758    ) -> (Option<String>, Vec<CapabilityProbe>) {
5759        let mut ran = Vec::new();
5760        let result = check_tracing_environment(namespaces, |probe| {
5761            ran.push(probe);
5762            Ok(!denied.contains(&probe))
5763        });
5764        (result.err().map(|error| error.to_string()), ran)
5765    }
5766
5767    /// Where unprivileged user namespaces are denied, a run that creates them
5768    /// is refused at the namespace probe, and a `--no-namespace` run, which
5769    /// never calls unshare, is not: it still passes the ptrace and seccomp
5770    /// probes (https://github.com/rrnewton/hermit/issues/4515).
5771    #[test]
5772    fn denied_namespaces_refuse_only_a_run_that_creates_them() {
5773        let denied = [CapabilityProbe::Namespaces];
5774        let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &denied);
5775        assert!(
5776            refusal
5777                .as_deref()
5778                .is_some_and(|refusal| refusal.contains("unshare(CLONE_NEWUSER | CLONE_NEWPID)")),
5779            "{refusal:?}"
5780        );
5781        assert_eq!(ran, [CapabilityProbe::Namespaces]);
5782        let (refusal, ran) = check_with_denied(NamespaceUse::None, &denied);
5783        assert_eq!(refusal, None);
5784        assert_eq!(ran, [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp]);
5785    }
5786
5787    /// A `--no-namespace` run is still refused where ptrace or seccomp is
5788    /// denied: skipping the namespace probe skips nothing else.
5789    #[test]
5790    fn a_run_without_namespaces_still_needs_ptrace_and_seccomp() {
5791        for denied in [CapabilityProbe::Ptrace, CapabilityProbe::Seccomp] {
5792            let (refusal, _) = check_with_denied(NamespaceUse::None, &[denied]);
5793            let expected = match denied {
5794                CapabilityProbe::Ptrace => "PTRACE_TRACEME",
5795                _ => "SECCOMP_SET_MODE_FILTER",
5796            };
5797            assert!(
5798                refusal
5799                    .as_deref()
5800                    .is_some_and(|refusal| refusal.contains(expected)),
5801                "{denied:?}: {refusal:?}"
5802            );
5803        }
5804        let (refusal, ran) = check_with_denied(NamespaceUse::Creates, &[]);
5805        assert_eq!(refusal, None);
5806        assert_eq!(
5807            ran,
5808            [
5809                CapabilityProbe::Namespaces,
5810                CapabilityProbe::Ptrace,
5811                CapabilityProbe::Seccomp
5812            ]
5813        );
5814    }
5815
5816    /// A run that drew an input from the host leaves a recording directory
5817    /// holding only `manifest.json`; `record rm` and `record clean` remove it
5818    /// as they remove a syscall recording, and still refuse a directory with
5819    /// neither marker (https://github.com/rrnewton/hermit/issues/4271).
5820    #[test]
5821    fn a_manifest_only_recording_can_be_removed() {
5822        let directory = tempfile::tempdir().unwrap();
5823        let data = HermitData::with_dir(directory.path());
5824        let id = Id::unique();
5825        let recording = directory.path().join(id.to_string());
5826        fs::create_dir_all(&recording).unwrap();
5827        assert!(data.remove(id).is_err());
5828        fs::write(recording.join(MANIFEST_NAME), "{}").unwrap();
5829        data.remove(id).unwrap();
5830        assert!(!recording.exists());
5831    }
5832
5833    /// The launch-time capture drops ephemeral host seed rows before ordering,
5834    /// so a seed's raw ID never enters the provenance Detcore checks guest
5835    /// views against, and every retained row keeps its place.
5836    #[test]
5837    fn identity_capture_excludes_host_seed_mounts_and_keeps_order() {
5838        let raw = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
5839                    76 10 0:50 / /mnt/xarfuse/uid-1/e62a203d-seed-nspid4026531836_cgpid16161-ns-4026531832 rw - fuse.squashfuse_ll squashfuse_ll rw\n\
5840                    20 10 0:7 / /test rw - tmpfs tmpfs rw\n\
5841                    30 10 0:51 / /mnt/xarfuse/stable-release rw - fuse.squashfuse_ll squashfuse_ll rw\n";
5842        let order = mountinfo_identity_order_from_raw(raw).unwrap();
5843        assert!(!order.contains(&76), "seed mount ID captured: {order:?}");
5844        assert_eq!(order, [10, 20, 30, 1]);
5845        assert_eq!(
5846            mountinfo_identity_order_from(raw).unwrap(),
5847            [10, 76, 20, 30, 1],
5848            "control: without the filter the seed ID is captured"
5849        );
5850    }
5851
5852    /// The namespace a test's captured provenance names.
5853    const NAMESPACE: detcore_model::config::MountNamespaceIdentity =
5854        detcore_model::config::MountNamespaceIdentity {
5855            id: Some(9001),
5856            device: 4,
5857            inode: 4026531840,
5858        };
5859
5860    #[test]
5861    fn kvm_mountinfo_config_preserves_captured_provenance() {
5862        let rewrite = detcore_model::config::MountInfoRootRewrite {
5863            raw_mount_id: 20,
5864            deterministic_root: b"/".to_vec(),
5865            raw_root_prefix: Some(b"/private-source".to_vec()),
5866            deterministic_root_prefix: Some(b"/tmp".to_vec()),
5867            raw_mountpoint_prefix: Some(b"/private-source".to_vec()),
5868            deterministic_mountpoint_prefix: Some(b"/tmp".to_vec()),
5869        };
5870        let mut config = DetConfig {
5871            mountinfo_mount_ids: vec![10, 20, 30],
5872            mountinfo_mount_ids_captured: true,
5873            mountinfo_mount_namespace: Some(NAMESPACE),
5874            mount_id_assignment_order: vec![700, 701],
5875            mountinfo_root_rewrites: vec![rewrite],
5876            mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
5877            ..DetConfig::default()
5878        };
5879        let mut expected = config.clone();
5880        expected.mountinfo_device_rewrites.clear();
5881        let (mut namespaces, mut captures) = (0, 0);
5882        prepare_kvm_mountinfo_config(
5883            &mut config,
5884            || {
5885                namespaces += 1;
5886                Ok(NAMESPACE)
5887            },
5888            || {
5889                captures += 1;
5890                Ok(vec![10, 30])
5891            },
5892        )
5893        .unwrap();
5894        assert_eq!(namespaces, 1, "the backend's namespace must be checked");
5895        assert_eq!(
5896            captures, 0,
5897            "the producer's snapshot is kept; the namespace is not read again"
5898        );
5899        assert_eq!(
5900            serde_json::to_value(&config).unwrap(),
5901            serde_json::to_value(&expected).unwrap(),
5902            "root rewrites, listed and assignment orders and every other setting must remain intact"
5903        );
5904    }
5905
5906    /// Provenance the backend keeps without reading the namespace again must
5907    /// be well formed by itself: these are the refusals a second, live capture
5908    /// used to supply (Codex post-facto review of dh-dt0n).
5909    #[test]
5910    fn kvm_mountinfo_config_refuses_malformed_captured_provenance() {
5911        let rewrite = |raw_mount_id| detcore_model::config::MountInfoRootRewrite {
5912            raw_mount_id,
5913            deterministic_root: b"/".to_vec(),
5914            raw_root_prefix: None,
5915            deterministic_root_prefix: None,
5916            raw_mountpoint_prefix: None,
5917            deterministic_mountpoint_prefix: None,
5918        };
5919        let valid = DetConfig {
5920            mountinfo_mount_ids: vec![10, 20, 1],
5921            mountinfo_mount_ids_captured: true,
5922            mountinfo_mount_namespace: Some(NAMESPACE),
5923            mount_id_assignment_order: vec![20],
5924            mountinfo_root_rewrites: vec![rewrite(20)],
5925            ..DetConfig::default()
5926        };
5927        prepare_kvm_mountinfo_config(
5928            &mut valid.clone(),
5929            || Ok(NAMESPACE),
5930            || panic!("captured provenance is not read again"),
5931        )
5932        .unwrap();
5933        let cases = [
5934            (
5935                "duplicate",
5936                DetConfig {
5937                    mountinfo_mount_ids: vec![10, 10],
5938                    ..valid.clone()
5939                },
5940                "malformed",
5941            ),
5942            (
5943                "empty",
5944                DetConfig {
5945                    mountinfo_mount_ids: vec![],
5946                    ..valid.clone()
5947                },
5948                "malformed",
5949            ),
5950            (
5951                "assigned twice",
5952                DetConfig {
5953                    mount_id_assignment_order: vec![20, 20],
5954                    ..valid.clone()
5955                },
5956                "malformed",
5957            ),
5958            (
5959                "zero assigned, unlisted",
5960                DetConfig {
5961                    mount_id_assignment_order: vec![0],
5962                    ..valid.clone()
5963                },
5964                "malformed",
5965            ),
5966            (
5967                "rewrite outside",
5968                DetConfig {
5969                    mountinfo_root_rewrites: vec![rewrite(30)],
5970                    ..valid.clone()
5971                },
5972                "root rewrite names mount 30",
5973            ),
5974        ];
5975        for (name, mut config, expected) in cases {
5976            let before = serde_json::to_value(&config).unwrap();
5977            let error = prepare_kvm_mountinfo_config(
5978                &mut config,
5979                || panic!("{name}: malformed provenance is refused before any read"),
5980                || panic!("{name}: captured provenance is not read again"),
5981            )
5982            .unwrap_err();
5983            assert!(error.to_string().contains(expected), "{name}: {error:#}");
5984            assert_eq!(serde_json::to_value(&config).unwrap(), before, "{name}");
5985        }
5986    }
5987
5988    /// Two reads of this process's namespace name it identically, and a
5989    /// kernel that reports a namespace ID reports a nonzero one.
5990    #[test]
5991    fn current_mount_namespace_is_stable_and_names_a_kernel_id_where_reported() {
5992        let first = current_mount_namespace().unwrap();
5993        assert_eq!(current_mount_namespace().unwrap(), first);
5994        assert_ne!(first.inode, 0);
5995        assert_ne!(first.id, Some(0));
5996    }
5997
5998    /// A host mount copied into the container can leave it between the
5999    /// producer's capture and the backend's start: Linux detaches the mounts on
6000    /// a dentry in every mount namespace when a host process removes that
6001    /// directory (`__detach_mounts`). The backend keeps the producer's order,
6002    /// which still names the row, and does not refuse; the order Detcore later
6003    /// validates guest views against is the producer's
6004    /// (minibeads dh-dt0n).
6005    #[test]
6006    fn kvm_mountinfo_config_keeps_a_snapshot_whose_host_row_left_the_namespace() {
6007        let producer = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6008                         20 10 0:22 / /proc rw - proc proc rw\n\
6009                         30 10 0:50 / /data/a rw - tmpfs tmpfs rw\n";
6010        let now = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6011                    20 10 0:22 / /proc rw - proc proc rw\n";
6012        let order = mountinfo_identity_order_from(producer).unwrap();
6013        let mut config = DetConfig {
6014            mountinfo_mount_ids: order.clone(),
6015            mountinfo_mount_ids_captured: true,
6016            mountinfo_mount_namespace: Some(NAMESPACE),
6017            ..DetConfig::default()
6018        };
6019        prepare_kvm_mountinfo_config(
6020            &mut config,
6021            || Ok(NAMESPACE),
6022            || mountinfo_identity_order_from(now),
6023        )
6024        .unwrap();
6025        assert_eq!(config.mountinfo_mount_ids, order);
6026        assert_eq!(config.mountinfo_mount_ids, [10, 20, 30, 1]);
6027        assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
6028            &mountinfo_identity_order_from(now).unwrap(),
6029            &config.mountinfo_mount_ids
6030        ));
6031    }
6032
6033    #[test]
6034    fn kvm_mountinfo_config_refuses_provenance_of_another_namespace() {
6035        let config = DetConfig {
6036            mountinfo_mount_ids: vec![10, 20, 1],
6037            mountinfo_mount_ids_captured: true,
6038            mountinfo_mount_namespace: Some(NAMESPACE),
6039            mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
6040            ..DetConfig::default()
6041        };
6042        // The first is a recycled nsfs inode: device and inode match, the
6043        // kernel's never-reused namespace ID does not.
6044        for backend in [
6045            detcore_model::config::MountNamespaceIdentity {
6046                id: Some(9002),
6047                ..NAMESPACE
6048            },
6049            detcore_model::config::MountNamespaceIdentity {
6050                inode: NAMESPACE.inode + 1,
6051                ..NAMESPACE
6052            },
6053            detcore_model::config::MountNamespaceIdentity {
6054                device: NAMESPACE.device + 1,
6055                ..NAMESPACE
6056            },
6057            detcore_model::config::MountNamespaceIdentity {
6058                id: None,
6059                ..NAMESPACE
6060            },
6061        ] {
6062            let mut stale = config.clone();
6063            let before = serde_json::to_value(&stale).unwrap();
6064            let error = prepare_kvm_mountinfo_config(
6065                &mut stale,
6066                || Ok(backend),
6067                || panic!("captured provenance is not read again"),
6068            )
6069            .unwrap_err();
6070            assert!(
6071                error.to_string().contains("name another mount namespace"),
6072                "{error:#}"
6073            );
6074            assert_eq!(serde_json::to_value(&stale).unwrap(), before);
6075        }
6076        let mut unnamed = DetConfig {
6077            mountinfo_mount_namespace: None,
6078            ..config.clone()
6079        };
6080        let before = serde_json::to_value(&unnamed).unwrap();
6081        let error = prepare_kvm_mountinfo_config(
6082            &mut unnamed,
6083            || panic!("provenance without a namespace is refused before any read"),
6084            || panic!("provenance without a namespace is refused before any read"),
6085        )
6086        .unwrap_err();
6087        assert!(
6088            error
6089                .to_string()
6090                .contains("do not name their mount namespace"),
6091            "{error:#}"
6092        );
6093        assert_eq!(serde_json::to_value(&unnamed).unwrap(), before);
6094        let mut unreadable = config;
6095        let before = serde_json::to_value(&unreadable).unwrap();
6096        let error = prepare_kvm_mountinfo_config(
6097            &mut unreadable,
6098            || Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
6099            || panic!("captured provenance is not read again"),
6100        )
6101        .unwrap_err();
6102        assert!(
6103            error
6104                .downcast_ref::<std::io::Error>()
6105                .is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
6106        );
6107        assert_eq!(serde_json::to_value(&unreadable).unwrap(), before);
6108    }
6109
6110    #[test]
6111    fn kvm_mountinfo_config_captures_validated_ambient_namespace() {
6112        let contents = b"80 20 8:1 / / rw - ext4 /dev/root rw\n\
6113                         10 80 0:7 / /test rw - tmpfs tmpfs rw\n";
6114        let mut config = DetConfig::default();
6115        let mut expected = config.clone();
6116        expected.mountinfo_mount_ids = vec![80, 10, 20];
6117        expected.mountinfo_mount_ids_captured = true;
6118        prepare_kvm_mountinfo_config(
6119            &mut config,
6120            || panic!("an ambient capture has no producer namespace to compare"),
6121            || mountinfo_identity_order_from(contents),
6122        )
6123        .unwrap();
6124        assert_eq!(
6125            serde_json::to_value(&config).unwrap(),
6126            serde_json::to_value(&expected).unwrap(),
6127            "visible rows precede parent-only IDs and no guest setting changes"
6128        );
6129        assert!(detcore_model::procfs::mount_ids_are_ordered_subset(
6130            &[80, 10],
6131            &config.mountinfo_mount_ids
6132        ));
6133        assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6134            &[10, 80],
6135            &config.mountinfo_mount_ids
6136        ));
6137        assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6138            &[80, 99],
6139            &config.mountinfo_mount_ids
6140        ));
6141        assert!(!detcore_model::procfs::mount_ids_are_ordered_subset(
6142            &[80, 80],
6143            &config.mountinfo_mount_ids
6144        ));
6145
6146        let mut empty = DetConfig::default();
6147        prepare_kvm_mountinfo_config(
6148            &mut empty,
6149            || panic!("an ambient capture has no producer namespace to compare"),
6150            || mountinfo_identity_order_from(b""),
6151        )
6152        .unwrap();
6153        assert!(empty.mountinfo_mount_ids.is_empty());
6154        assert!(empty.mountinfo_mount_ids_captured);
6155    }
6156
6157    #[test]
6158    fn kvm_mountinfo_config_refuses_missing_or_malformed_capture() {
6159        let valid = b"10 20 8:1 / / rw - ext4 /dev/root rw\n";
6160        let config = DetConfig {
6161            mountinfo_device_rewrites: vec![(libc::makedev(0, 1), libc::makedev(8, 1))],
6162            ..DetConfig::default()
6163        };
6164        for contents in [
6165            b"malformed".as_slice(),
6166            b"10 20 8:1 / / rw - ext4 /dev/root rw\n10 20 8:1 / / rw - ext4 /dev/root rw\n",
6167            b"10 20 8:1 / / rw unknown:7 - ext4 /dev/root rw\n",
6168        ] {
6169            let mut candidate = config.clone();
6170            let before = serde_json::to_value(&candidate).unwrap();
6171            let error = prepare_kvm_mountinfo_config(
6172                &mut candidate,
6173                || panic!("an ambient capture has no producer namespace to compare"),
6174                || mountinfo_identity_order_from(contents),
6175            )
6176            .unwrap_err();
6177            assert!(format!("{error:#}").contains("malformed mountinfo"));
6178            assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
6179        }
6180        let mut candidate = config;
6181        let before = serde_json::to_value(&candidate).unwrap();
6182        let error = prepare_kvm_mountinfo_config(
6183            &mut candidate,
6184            || panic!("an ambient capture has no producer namespace to compare"),
6185            || Err(std::io::Error::from(std::io::ErrorKind::PermissionDenied).into()),
6186        )
6187        .unwrap_err();
6188        assert!(
6189            error
6190                .downcast_ref::<std::io::Error>()
6191                .is_some_and(|error| error.kind() == std::io::ErrorKind::PermissionDenied)
6192        );
6193        assert_eq!(serde_json::to_value(&candidate).unwrap(), before);
6194        assert_eq!(mountinfo_identity_order_from(valid).unwrap(), [10, 20]);
6195    }
6196
6197    #[test]
6198    fn kvm_mountinfo_config_refuses_uncaptured_provenance_vectors() {
6199        for (listed, assigned, namespace) in [
6200            (vec![10], vec![], None),
6201            (vec![], vec![700], None),
6202            (vec![], vec![], Some(NAMESPACE)),
6203        ] {
6204            let mut config = DetConfig {
6205                mountinfo_mount_ids: listed,
6206                mount_id_assignment_order: assigned,
6207                mountinfo_mount_namespace: namespace,
6208                ..DetConfig::default()
6209            };
6210            let before = serde_json::to_value(&config).unwrap();
6211            let error = prepare_kvm_mountinfo_config(
6212                &mut config,
6213                || panic!("must not overwrite incomplete provenance"),
6214                || panic!("must not overwrite incomplete provenance"),
6215            )
6216            .unwrap_err();
6217            assert!(error.to_string().contains("no producer-captured namespace"));
6218            assert_eq!(serde_json::to_value(&config).unwrap(), before);
6219        }
6220    }
6221
6222    /// The container mount table Detcore renders on KVM must name mounts of
6223    /// the namespace the backend captured
6224    /// (https://github.com/rrnewton/hermit/issues/4213, K3a).
6225    #[test]
6226    fn kvm_mountinfo_config_refuses_a_mount_table_of_another_namespace() {
6227        let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6228                          20 10 0:22 / /proc rw - proc proc rw\n\
6229                          40 10 0:23 / /elsewhere rw - tmpfs tmpfs rw\n";
6230        let rows = detcore_model::container_mounts::parse_container_mounts(namespace).unwrap();
6231        let table = |installed: &[u64]| {
6232            detcore_model::container_mounts::ContainerMountTable::select(
6233                &rows,
6234                &installed.iter().copied().collect(),
6235                &[],
6236                &std::collections::BTreeSet::new(),
6237            )
6238        };
6239        let config = |table| DetConfig {
6240            mountinfo_mount_ids: vec![10, 20, 1],
6241            mountinfo_mount_ids_captured: true,
6242            mountinfo_mount_namespace: Some(NAMESPACE),
6243            container_mount_table: Some(table),
6244            ..DetConfig::default()
6245        };
6246        let snapshot = || -> Result<Vec<u64>, Error> { panic!("the snapshot is kept") };
6247        let mut matching = config(table(&[20]));
6248        prepare_kvm_mountinfo_config(&mut matching, || Ok(NAMESPACE), snapshot).unwrap();
6249        let mut stale = config(table(&[40]));
6250        let error =
6251            prepare_kvm_mountinfo_config(&mut stale, || Ok(NAMESPACE), snapshot).unwrap_err();
6252        assert!(error.to_string().contains("names mount 40"), "{error:#}");
6253    }
6254
6255    /// A run in a namespace Hermit made no mount in shows only the base
6256    /// mountpoints mounted at their very paths, maps a file on any other
6257    /// mount to its nearest shown ancestor, and validates against an order
6258    /// read from the same bytes (https://github.com/rrnewton/hermit/issues/4213).
6259    #[test]
6260    fn an_unplanned_table_shows_only_the_base_mountpoints() {
6261        let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n\
6262                          20 10 0:22 / /proc rw - proc proc rw\n\
6263                          30 10 0:23 / /dev rw - devtmpfs dev rw\n\
6264                          40 10 0:24 / /data/eden rw - fuse.edenfs eden rw\n\
6265                          41 30 0:25 / /dev/shm rw - tmpfs tmpfs rw\n\
6266                          50 10 0:26 / /run/user/1000 rw - tmpfs tmpfs rw\n";
6267        // /run is no mount here: its descriptor reaches the root mount.
6268        let base = [
6269            (b"/".to_vec(), 10),
6270            (b"/proc".to_vec(), 20),
6271            (b"/dev".to_vec(), 30),
6272            (b"/dev/shm".to_vec(), 41),
6273            (b"/run".to_vec(), 10),
6274        ];
6275        for mountpoint in detcore_model::container_mounts::BASE_MOUNTPOINTS {
6276            assert!(
6277                !mountpoint.bytes().any(|byte| b" \t\n\\".contains(&byte)),
6278                "{mountpoint} needs mountinfo escaping"
6279            );
6280        }
6281        let no_launch = std::collections::BTreeSet::new();
6282        let (table, order) =
6283            unplanned_container_mount_table_from(namespace, &no_launch, &base).unwrap();
6284        assert_eq!(table.shown_mount_ids(), [10, 20, 30, 41].into());
6285        assert_eq!(table.shown_mount_id(40), 10);
6286        assert_eq!(table.shown_mount_id(50), 10);
6287        assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
6288        let rendered = String::from_utf8(table.mountinfo()).unwrap();
6289        assert!(!rendered.contains("/data/eden") && !rendered.contains("/run/user"));
6290        // A launch from a checkout on /data/eden shows that mount too; a
6291        // file on the still hidden /run/user/1000 reports the root.
6292        let launch = [40].into();
6293        let (table, order) =
6294            unplanned_container_mount_table_from(namespace, &launch, &base).unwrap();
6295        assert_eq!(table.shown_mount_ids(), [10, 20, 30, 40, 41].into());
6296        assert_eq!(table.shown_mount_id(40), 40);
6297        assert_eq!(table.shown_mount_id(50), 10);
6298        assert_eq!(order, [10, 20, 30, 40, 41, 50, 1]);
6299    }
6300
6301    /// Runs test `name` again under `unshare --user --map-root-user
6302    /// --mount`, where it may mount, and returns true in this process, which
6303    /// then has nothing more to check; returns false in that child, which runs
6304    /// the test's body. `unshare(CLONE_NEWUSER)` refuses a multithreaded
6305    /// process, so the test cannot enter one itself. Where user namespaces
6306    /// are unavailable the test is skipped, saying why.
6307    fn rerun_in_user_namespace(name: &str) -> bool {
6308        const CHILD: &str = "HERMIT_TEST_USER_NAMESPACE_CHILD";
6309        if std::env::var_os(CHILD).is_some() {
6310            return false;
6311        }
6312        let probe = std::process::Command::new("unshare")
6313            .args(["--user", "--map-root-user", "--mount", "true"])
6314            .output();
6315        if !probe.as_ref().is_ok_and(|probe| probe.status.success()) {
6316            eprintln!("SKIPPED {name}: user namespaces are unavailable here: {probe:?}");
6317            return true;
6318        }
6319        let output = std::process::Command::new("unshare")
6320            .args(["--user", "--map-root-user", "--mount", "--"])
6321            .arg(std::env::current_exe().unwrap())
6322            .args(["--exact", name, "--nocapture", "--test-threads=1"])
6323            .env(CHILD, "1")
6324            .output()
6325            .expect("run the test under unshare");
6326        let stdout = String::from_utf8_lossy(&output.stdout);
6327        assert!(
6328            output.status.success() && stdout.contains("1 passed"),
6329            "the child failed or ran no test:\n{stdout}\n{}",
6330            String::from_utf8_lossy(&output.stderr)
6331        );
6332        true
6333    }
6334
6335    /// A library caller's thread with a mount namespace of its own captures
6336    /// its own namespace's rows, identity and mount IDs (all through
6337    /// `/proc/thread-self`), not the thread group leader's: otherwise the
6338    /// leader's rows and the thread's descriptor mount IDs never meet, and
6339    /// the table shows nothing, not even `/`. A thread may unshare its mount
6340    /// namespace only with CAP_SYS_ADMIN, which an unprivileged test gets in
6341    /// a user namespace of its own (`rerun_in_user_namespace`); there the test
6342    /// thread, not the leader, unshares the mount namespace.
6343    #[test]
6344    fn a_thread_with_its_own_mount_namespace_captures_its_own_view() {
6345        use std::os::unix::fs::MetadataExt;
6346        if rerun_in_user_namespace(
6347            "tests::a_thread_with_its_own_mount_namespace_captures_its_own_view",
6348        ) {
6349            return;
6350        }
6351        let checked = std::thread::spawn(|| {
6352            // SAFETY: unshare takes no pointer.
6353            assert_eq!(
6354                unsafe { libc::unshare(libc::CLONE_NEWNS) },
6355                0,
6356                "unshare(CLONE_NEWNS): {}",
6357                io::Error::last_os_error()
6358            );
6359            let own = current_mount_namespace().unwrap();
6360            let leader = fs::metadata("/proc/self/ns/mnt").unwrap();
6361            assert_ne!(
6362                own.inode,
6363                leader.ino(),
6364                "the thread kept the leader's namespace"
6365            );
6366            let (table, order) = unplanned_container_mount_table(Path::new(".")).unwrap();
6367            assert!(
6368                table
6369                    .mounts
6370                    .iter()
6371                    .any(|row| row.mountpoint.as_slice() == b"/"),
6372                "the thread's table shows no /: {table:?}"
6373            );
6374            let root = thread_mount_id_of(Path::new("/")).unwrap();
6375            assert!(table.shown_mount_ids().contains(&root));
6376            assert!(table.shown_mount_ids().iter().all(|id| order.contains(id)));
6377        })
6378        .join();
6379        assert!(checked.is_ok(), "the thread's checks failed");
6380    }
6381
6382    /// The launch directory is resolved and held before the mount table is
6383    /// read: a mount made on it between the two (here a tmpfs over it, in a
6384    /// user and mount namespace of the test's own) is not the launch mount,
6385    /// because the held directory is below it; the mount the directory was
6386    /// on is, and it is in the rows read. Had the directory been resolved
6387    /// after the read, it would have reached the new tmpfs. The same order
6388    /// puts a mount that resolving the directory triggers (an automount on
6389    /// its path) in the rows read.
6390    #[test]
6391    fn launch_directories_are_held_before_the_mount_table_is_read() {
6392        if rerun_in_user_namespace(
6393            "tests::launch_directories_are_held_before_the_mount_table_is_read",
6394        ) {
6395            return;
6396        }
6397        let directory = tempfile::tempdir().unwrap();
6398        let launch = directory.path().join("launch");
6399        fs::create_dir(&launch).unwrap();
6400        let before = thread_mount_id_of(&launch).unwrap();
6401        let target = launch.clone();
6402        let (table, _) = unplanned_container_mount_table_with(&launch, move || {
6403            let status = std::process::Command::new("mount")
6404                .args(["-t", "tmpfs", "none"])
6405                .arg(&target)
6406                .status()
6407                .expect("run mount");
6408            assert!(status.success(), "mount a tmpfs over the launch directory");
6409            thread_mountinfo()
6410        })
6411        .unwrap();
6412        let over = thread_mount_id_of(&launch).unwrap();
6413        assert_ne!(over, before, "the tmpfs did not cover the launch directory");
6414        assert!(table.shown_mount_ids().contains(&before));
6415        assert!(!table.shown_mount_ids().contains(&over));
6416        let _ = std::process::Command::new("umount").arg(&launch).status();
6417    }
6418
6419    /// A launch mount the mount table read does not list is refused, not
6420    /// dropped from the table.
6421    #[test]
6422    fn a_launch_mount_missing_from_the_read_is_refused() {
6423        let namespace = b"10 1 8:1 / / rw - ext4 /dev/root rw\n";
6424        let error = unplanned_container_mount_table_from(namespace, &[99].into(), &[])
6425            .unwrap_err()
6426            .to_string();
6427        assert!(error.contains("launch mount 99"), "{error}");
6428    }
6429
6430    #[test]
6431    fn skid_overshoot_report_covers_success_error_and_disabled_backends() {
6432        let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
6433        let _ = reverie::take_skid_overshoot_count();
6434
6435        reverie::record_skid_overshoot();
6436        let empty_run = SkidOvershootReport::begin(true);
6437        assert_eq!(
6438            reverie::take_skid_overshoot_count(),
6439            0,
6440            "begin must clear evidence from a previous invocation"
6441        );
6442        empty_run.finish(Ok::<_, Error>(())).unwrap();
6443
6444        let success = SkidOvershootReport::begin(true);
6445        reverie::record_skid_overshoot();
6446        reverie::record_skid_overshoot();
6447        let error = success.finish(Ok::<_, Error>(7)).unwrap_err();
6448        assert_eq!(
6449            error
6450                .downcast_ref::<SkidOvershootError>()
6451                .expect("skid refusal must remain typed")
6452                .count(),
6453            2
6454        );
6455        assert!(
6456            error
6457                .to_string()
6458                .contains("observed 2 HERMIT_SKID_OVERSHOOT report(s)"),
6459            "{error:#}"
6460        );
6461        assert!(
6462            error
6463                .to_string()
6464                .contains("deterministic execution was not established"),
6465            "{error:#}"
6466        );
6467        assert_eq!(reverie::take_skid_overshoot_count(), 0);
6468
6469        let error = SkidOvershootReport::begin(true);
6470        reverie::record_skid_overshoot();
6471        let error = error
6472            .finish(Err::<(), _>(anyhow!("guest failed")))
6473            .unwrap_err();
6474        assert!(error.downcast_ref::<SkidOvershootError>().is_some());
6475        let error = format!("{error:#}");
6476        assert!(error.contains("guest failed"), "{error}");
6477        assert!(
6478            error.contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)"),
6479            "{error}"
6480        );
6481        assert_eq!(reverie::take_skid_overshoot_count(), 0);
6482
6483        reverie::record_skid_overshoot();
6484        let disabled = SkidOvershootReport::begin(false);
6485        disabled.finish(Ok::<_, Error>(())).unwrap();
6486        assert_eq!(
6487            reverie::take_skid_overshoot_count(),
6488            1,
6489            "a backend that cannot produce ptrace PMU overshoots must not consume another run's evidence"
6490        );
6491    }
6492
6493    #[test]
6494    fn only_ptrace_hosted_backends_consume_skid_overshoot_reports() {
6495        for backend in [Backend::Ptrace, Backend::E9patch] {
6496            assert!(backend.uses_ptrace_pmu_timers(), "{backend:?}");
6497        }
6498        for backend in [Backend::Dbt, Backend::Sabre, Backend::Kvm] {
6499            assert!(!backend.uses_ptrace_pmu_timers(), "{backend:?}");
6500        }
6501        // In-guest Detcore has no ptrace tracer to arm the PMU timer from.
6502        assert!(!Backend::Liteinst.uses_ptrace_pmu_timers());
6503        assert!(!Backend::InGuestTrap.uses_ptrace_pmu_timers());
6504    }
6505
6506    #[cfg(feature = "liteinst")]
6507    fn write_guest_program(directory: &Path, name: &str, bytes: &[u8], mode: u32) -> PathBuf {
6508        let path = directory.join(name);
6509        fs::write(&path, bytes).unwrap();
6510        fs::set_permissions(&path, fs::Permissions::from_mode(mode)).unwrap();
6511        // The kernel may clear a set-group-ID bit that this user cannot set;
6512        // a test that silently lost its bit would test nothing.
6513        assert_eq!(
6514            fs::metadata(&path).unwrap().permissions().mode() & 0o7777,
6515            mode,
6516            "{}",
6517            path.display()
6518        );
6519        path
6520    }
6521
6522    #[cfg(feature = "liteinst")]
6523    fn shebang_to(interpreter: &Path) -> Vec<u8> {
6524        let mut script = b"#!".to_vec();
6525        script.extend_from_slice(interpreter.as_os_str().as_bytes());
6526        script.extend_from_slice(b" -e\necho script\n");
6527        script
6528    }
6529
6530    #[test]
6531    #[cfg(feature = "liteinst")]
6532    fn in_guest_liteinst_runs_a_dynamically_linked_x86_64_program() {
6533        use interp::startup_fixtures::dynamic_executable;
6534
6535        let directory = tempfile::tempdir().unwrap();
6536        let program = write_guest_program(
6537            directory.path(),
6538            "dynamic",
6539            &dynamic_executable(false),
6540            0o755,
6541        );
6542        assert_eq!(
6543            in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap(),
6544            None
6545        );
6546    }
6547
6548    #[test]
6549    #[cfg(feature = "liteinst")]
6550    fn in_guest_liteinst_refuses_programs_that_start_before_the_runtime() {
6551        use interp::startup_fixtures::*;
6552
6553        let directory = tempfile::tempdir().unwrap();
6554        let cases: [(&str, Vec<u8>, &str); 4] = [
6555            (
6556                "static",
6557                elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6558                "is statically linked",
6559            ),
6560            (
6561                "preinit",
6562                dynamic_executable(true),
6563                "has a DT_PREINIT_ARRAY",
6564            ),
6565            (
6566                "aarch64",
6567                elf(EM_AARCH64, &[(PT_INTERP, INTERP)]),
6568                "is not a 64-bit x86-64 ELF image",
6569            ),
6570            (
6571                "text",
6572                b"plain text, no #! line\n".to_vec(),
6573                "is neither an ELF executable nor a #! script",
6574            ),
6575        ];
6576        for (name, bytes, reason) in cases {
6577            let program = write_guest_program(directory.path(), name, &bytes, 0o755);
6578            let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
6579                .unwrap()
6580                .unwrap_or_else(|| panic!("{name} was not refused"));
6581            assert!(
6582                gap.contains(reason) && gap.contains(&program.display().to_string()),
6583                "{name}: {gap}"
6584            );
6585        }
6586    }
6587
6588    /// A failure recorded during an in-guest run fails the settle step and
6589    /// latches a determinism loss, so verification refuses the run (Codex
6590    /// implementation review, HIGH 3 and 4).
6591    #[tokio::test]
6592    #[cfg(feature = "liteinst")]
6593    async fn a_recorded_in_guest_failure_fails_the_run_and_latches_a_loss() {
6594        use std::os::fd::FromRawFd;
6595
6596        use reverie::GlobalTool;
6597        use reverie_rpc_transport::ConnectionAdmission;
6598
6599        let config = DetConfig::default().with_backend(|backend| {
6600            backend.process_exits_complete_asynchronously = true;
6601        });
6602        let global_state = detcore::GlobalState::init_global_state(&config).await;
6603        let exits = in_guest_exits::InGuestExitAdmission::default();
6604        // Admitting before any reporter is attached is refused and recorded.
6605        let fd = unsafe { libc::syscall(libc::SYS_pidfd_open, std::process::id() as i32, 0) };
6606        assert!(fd >= 0);
6607        let pidfd = unsafe { std::os::fd::OwnedFd::from_raw_fd(fd as i32) };
6608        assert!(exits.admit(pidfd).is_err());
6609        let error = settle_in_guest_exits(&exits, &global_state)
6610            .await
6611            .expect_err("a recorded failure must fail the run");
6612        assert!(
6613            error
6614                .to_string()
6615                .starts_with("in-guest LiteInst refused a guest connection:"),
6616            "{error}"
6617        );
6618        assert!(detcore::detlog::determinism_loss().is_some());
6619    }
6620
6621    #[test]
6622    fn in_guest_trap_is_in_guest_liteinst_and_forces_site_patching_off() {
6623        assert!(Backend::Liteinst.is_in_guest_liteinst());
6624        assert!(Backend::InGuestTrap.is_in_guest_liteinst());
6625        for backend in [
6626            Backend::Ptrace,
6627            Backend::Dbt,
6628            Backend::Sabre,
6629            Backend::Kvm,
6630            Backend::E9patch,
6631        ] {
6632            assert!(!backend.is_in_guest_liteinst(), "{backend:?}");
6633            assert_eq!(backend.runtime_name(), backend.as_str(), "{backend:?}");
6634            assert_eq!(forced_site_patching_value(backend), None, "{backend:?}");
6635        }
6636        assert_eq!(Backend::InGuestTrap.as_str(), "in-guest-trap");
6637        assert_eq!(Backend::InGuestTrap.runtime_name(), "liteinst");
6638        assert_eq!(Backend::Liteinst.runtime_name(), "liteinst");
6639        // liteinst leaves the variable to the guest environment.
6640        assert_eq!(forced_site_patching_value(Backend::Liteinst), None);
6641        assert_eq!(forced_site_patching_value(Backend::InGuestTrap), Some("0"));
6642        // The CLI spelling parses to the variant and back.
6643        assert_eq!(
6644            <Backend as ValueEnum>::from_str("in-guest-trap", false),
6645            Ok(Backend::InGuestTrap)
6646        );
6647        assert!(Backend::ALL.contains(&Backend::InGuestTrap));
6648        for backend in Backend::ALL {
6649            let name = backend
6650                .to_possible_value()
6651                .expect("every backend is a visible CLI value");
6652            assert_eq!(name.get_name(), backend.as_str(), "{backend:?}");
6653        }
6654    }
6655
6656    /// in-guest-trap sets `REVERIE_LITEINST_SITE_PATCHING=0` on the guest
6657    /// command when the guest environment leaves it unset or already `0`, and
6658    /// refuses, before anything starts, an environment that sets any other
6659    /// value; the refusal names the value and both ways out. liteinst neither
6660    /// refuses nor changes the variable.
6661    #[test]
6662    #[cfg(feature = "liteinst")]
6663    fn in_guest_trap_refuses_a_guest_environment_that_turns_site_patching_on() {
6664        use std::ffi::OsStr;
6665
6666        let name = reverie_liteinst::SITE_PATCHING_ENV;
6667        let mut unset = Command::new("/bin/true");
6668        unset.env_remove(name);
6669        assert_eq!(
6670            in_guest_trap_site_patching_conflict(&unset, Backend::InGuestTrap),
6671            None
6672        );
6673        force_in_guest_site_patching(&mut unset, Backend::InGuestTrap);
6674        assert_eq!(unset.get_env(name).as_deref(), Some(OsStr::new("0")));
6675
6676        let mut zero = Command::new("/bin/true");
6677        zero.env(name, "0");
6678        assert_eq!(
6679            in_guest_trap_site_patching_conflict(&zero, Backend::InGuestTrap),
6680            None
6681        );
6682
6683        for value in ["1", "", "yes", " 0"] {
6684            let mut command = Command::new("/bin/true");
6685            command.env(name, value);
6686            let conflict = in_guest_trap_site_patching_conflict(&command, Backend::InGuestTrap)
6687                .unwrap_or_else(|| panic!("{value:?} was accepted"));
6688            assert!(conflict.contains(&format!("{name}={value},")), "{conflict}");
6689            assert!(conflict.contains("--backend=liteinst"), "{conflict}");
6690            assert!(conflict.contains("drop the variable"), "{conflict}");
6691            // The whole refusal path stops on it first, before the program,
6692            // kernel or timeslice checks, and leaves the value untouched.
6693            let error = refuse_in_guest_liteinst_run(
6694                &mut command,
6695                &DetConfig::default(),
6696                Backend::InGuestTrap,
6697            )
6698            .unwrap_err();
6699            let refusal = error
6700                .downcast_ref::<LiteinstInGuestRefusal>()
6701                .expect("a typed in-guest refusal, which the CLI reports as exit 122");
6702            assert!(
6703                refusal.to_string().starts_with(
6704                    "--backend=in-guest-trap (in-guest LiteInst, site patching off) refuses \
6705                     this run: the guest environment sets"
6706                ),
6707                "{refusal}"
6708            );
6709            assert_eq!(command.get_env(name).as_deref(), Some(OsStr::new(value)));
6710
6711            // liteinst takes the variable from the guest environment as it is.
6712            let mut liteinst = Command::new("/bin/true");
6713            liteinst.env(name, value);
6714            assert_eq!(
6715                in_guest_trap_site_patching_conflict(&liteinst, Backend::Liteinst),
6716                None
6717            );
6718            force_in_guest_site_patching(&mut liteinst, Backend::Liteinst);
6719            assert_eq!(liteinst.get_env(name).as_deref(), Some(OsStr::new(value)));
6720        }
6721    }
6722
6723    /// The coordinator's postcondition for an in-guest-trap run: a record
6724    /// with no patched and no candidate site passes; a patched site, a
6725    /// candidate, an unmeasured count or a missing record is refused, with a
6726    /// typed in-guest refusal and a determinism loss. Other backends are not
6727    /// held to it.
6728    #[test]
6729    #[cfg(feature = "liteinst")]
6730    fn an_in_guest_trap_run_that_patched_a_site_is_refused_after_it_ends() {
6731        let record = |candidates: Option<u64>, patched: Option<u64>| {
6732            reverie::DispatchStats::new(
6733                "in-guest-trap",
6734                reverie::DispatchCounters::ZERO,
6735                reverie::SiteCounters {
6736                    candidates,
6737                    patched,
6738                    fell_back: Some(0),
6739                },
6740            )
6741        };
6742        let clean = record(Some(0), Some(0));
6743        assert_eq!(
6744            in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 1),
6745            None
6746        );
6747        for (candidates, patched, shown) in [
6748            (Some(3), Some(3), "3 patched and 3 candidate"),
6749            (Some(1), Some(0), "0 patched and 1 candidate"),
6750            (Some(0), None, "unmeasured patched and 0 candidate"),
6751        ] {
6752            let reason = in_guest_trap_patching_evidence(
6753                Backend::InGuestTrap,
6754                Some(&record(candidates, patched)),
6755                1,
6756            )
6757            .unwrap_or_else(|| panic!("{candidates:?} {patched:?} was accepted"));
6758            assert!(reason.contains(shown), "{reason}");
6759        }
6760        assert!(
6761            in_guest_trap_patching_evidence(Backend::InGuestTrap, None, 1)
6762                .is_some_and(|reason| reason.contains("no LiteInst dispatch record"))
6763        );
6764        // An empty record from guests that collected nothing is not zero.
6765        assert!(
6766            in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&clean), 0)
6767                .is_some_and(|reason| reason.contains("no guest process reported"))
6768        );
6769        let patched = record(Some(3), Some(3));
6770        assert_eq!(
6771            in_guest_trap_patching_evidence(Backend::Liteinst, Some(&patched), 1),
6772            None
6773        );
6774        assert_eq!(
6775            in_guest_trap_patching_evidence(Backend::Liteinst, None, 0),
6776            None
6777        );
6778
6779        refuse_in_guest_trap_patching(Backend::InGuestTrap, None).unwrap();
6780        let error = refuse_in_guest_trap_patching(
6781            Backend::InGuestTrap,
6782            in_guest_trap_patching_evidence(Backend::InGuestTrap, Some(&patched), 1),
6783        )
6784        .unwrap_err();
6785        assert!(
6786            error.downcast_ref::<LiteinstInGuestRefusal>().is_some(),
6787            "{error:#}"
6788        );
6789        assert!(
6790            error
6791                .to_string()
6792                .starts_with("--backend=in-guest-trap (in-guest LiteInst, site patching off)"),
6793            "{error:#}"
6794        );
6795        assert!(
6796            detcore::detlog::determinism_loss().is_some_and(|loss| loss.contains("3 patched")),
6797            "the refusal must record a determinism loss"
6798        );
6799    }
6800
6801    /// Only an in-guest-trap run tells every Tool image to check the settings
6802    /// its runtime captured, and that run always collects the statistics the
6803    /// check requires.
6804    #[test]
6805    #[cfg(feature = "liteinst")]
6806    fn only_in_guest_trap_asks_tool_images_to_check_their_runtime() {
6807        for backend in Backend::ALL {
6808            let checks = in_guest_site_patching_off(backend);
6809            assert_eq!(checks, backend == Backend::InGuestTrap, "{backend:?}");
6810            if checks {
6811                assert!(in_guest_stats_request(backend, &None).is_enabled());
6812            }
6813        }
6814        assert!(!in_guest_stats_request(Backend::Liteinst, &None).is_enabled());
6815    }
6816
6817    #[test]
6818    #[cfg(feature = "liteinst")]
6819    fn in_guest_liteinst_refuses_a_kernel_older_than_6_5() {
6820        for release in [
6821            "6.5.0",
6822            "6.5",
6823            "6.10.3-200.fc40.x86_64",
6824            "7.1.3-0_fbk0_rc18",
6825            "10.0",
6826        ] {
6827            assert_eq!(in_guest_liteinst_kernel_gap(release), None, "{release}");
6828        }
6829        for release in ["6.4.16", "5.15.0-91-generic", "4.19"] {
6830            let gap = in_guest_liteinst_kernel_gap(release)
6831                .unwrap_or_else(|| panic!("{release} was not refused"));
6832            assert!(gap.contains("Linux 6.5 or later"), "{gap}");
6833            assert!(gap.contains(release), "{gap}");
6834        }
6835        for release in ["", "unknown", "6"] {
6836            assert!(
6837                in_guest_liteinst_kernel_gap(release).is_some(),
6838                "{release:?}"
6839            );
6840        }
6841        // No assertion about the kernel running the tests: that would make
6842        // the test's result depend on the host, and the releases above
6843        // already test both sides of the floor.
6844    }
6845
6846    #[test]
6847    #[cfg(feature = "liteinst")]
6848    fn in_guest_liteinst_refuses_secure_execution_images() {
6849        use interp::startup_fixtures::dynamic_executable;
6850
6851        let directory = tempfile::tempdir().unwrap();
6852        let bytes = dynamic_executable(false);
6853        let gap = |name: &str, mode: u32| {
6854            let program = write_guest_program(directory.path(), name, &bytes, mode);
6855            in_guest_liteinst_program_gap(&mut Command::new(&program)).unwrap()
6856        };
6857        for (name, mode) in [("setuid", 0o4755), ("setgid", 0o2755)] {
6858            let refusal = gap(name, mode).unwrap_or_else(|| panic!("{name} was not refused"));
6859            assert!(refusal.contains("secure-execution mode"), "{refusal}");
6860        }
6861        // Without group execute the kernel treats set-group-ID as mandatory
6862        // locking, not a credential change, so the loader honours LD_PRELOAD.
6863        assert_eq!(gap("setgid-no-group-exec", 0o2744), None);
6864    }
6865
6866    #[test]
6867    #[cfg(feature = "liteinst")]
6868    fn in_guest_liteinst_checks_scripts_through_their_interpreter() {
6869        use interp::startup_fixtures::*;
6870
6871        let directory = tempfile::tempdir().unwrap();
6872        let dynamic = write_guest_program(
6873            directory.path(),
6874            "dynamic",
6875            &dynamic_executable(false),
6876            0o755,
6877        );
6878        let static_elf = write_guest_program(
6879            directory.path(),
6880            "static",
6881            &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6882            0o755,
6883        );
6884
6885        let script = write_guest_program(
6886            directory.path(),
6887            "to-static",
6888            &shebang_to(&static_elf),
6889            0o755,
6890        );
6891        let gap = in_guest_liteinst_program_gap(&mut Command::new(&script))
6892            .unwrap()
6893            .expect("a script run by a static interpreter was not refused");
6894        assert!(
6895            gap.contains(&static_elf.display().to_string()) && gap.contains("statically linked"),
6896            "{gap}"
6897        );
6898
6899        // A relative interpreter resolves against the guest's working directory.
6900        let relative = write_guest_program(directory.path(), "relative", b"#!static\n", 0o755);
6901        let gap =
6902            in_guest_liteinst_program_gap(Command::new(&relative).current_dir(directory.path()))
6903                .unwrap()
6904                .expect("a relative static interpreter was not refused");
6905        assert!(gap.contains("statically linked"), "{gap}");
6906
6907        // The kernel keeps a carriage return in the interpreter path, so a
6908        // script with CRLF line endings runs `interp\r`, not `interp`.
6909        write_guest_program(
6910            directory.path(),
6911            "interp",
6912            &dynamic_executable(false),
6913            0o755,
6914        );
6915        let interp_cr = write_guest_program(
6916            directory.path(),
6917            "interp\r",
6918            &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
6919            0o755,
6920        );
6921        let mut crlf = b"#!".to_vec();
6922        crlf.extend_from_slice(directory.path().join("interp").as_os_str().as_bytes());
6923        crlf.extend_from_slice(b"\r\necho script\r\n");
6924        let crlf = write_guest_program(directory.path(), "crlf", &crlf, 0o755);
6925        let gap = in_guest_liteinst_program_gap(&mut Command::new(&crlf))
6926            .unwrap()
6927            .expect("a CRLF script run by a static interp\\r was not refused");
6928        assert!(
6929            gap.contains(&interp_cr.display().to_string()) && gap.contains("statically linked"),
6930            "{gap}"
6931        );
6932
6933        // A #! line the kernel's script handler declines runs no interpreter:
6934        // the kernel fails the execve or tries another handler, so it is
6935        // refused.
6936        let mut truncated = b"#!/".to_vec();
6937        truncated.resize(256, b'a');
6938        for (name, bytes) in [
6939            ("empty", b"#! \t\nbody\n".to_vec()),
6940            ("truncated", truncated),
6941        ] {
6942            let program = write_guest_program(directory.path(), name, &bytes, 0o755);
6943            let gap = in_guest_liteinst_program_gap(&mut Command::new(&program))
6944                .unwrap()
6945                .unwrap_or_else(|| panic!("{name} was not refused"));
6946            assert!(
6947                gap.contains("the kernel's script handler declines it"),
6948                "{name}: {gap}"
6949            );
6950        }
6951
6952        // Four nested scripts are followed to the ELF image; a fifth is refused.
6953        let mut target = dynamic;
6954        for level in 1..=5 {
6955            target = write_guest_program(
6956                directory.path(),
6957                &format!("level-{level}"),
6958                &shebang_to(&target),
6959                0o755,
6960            );
6961            let gap = in_guest_liteinst_program_gap(&mut Command::new(&target)).unwrap();
6962            if level <= MAX_INTERPRETER_DEPTH {
6963                assert_eq!(gap, None, "level {level}");
6964            } else {
6965                let gap = gap.expect("five nested scripts were not refused");
6966                assert!(gap.contains("nest more than 4 deep"), "{gap}");
6967            }
6968        }
6969    }
6970
6971    #[test]
6972    #[cfg(feature = "liteinst")]
6973    fn in_guest_liteinst_refuses_a_fifo_without_blocking() {
6974        let directory = tempfile::tempdir().unwrap();
6975        let fifo = directory.path().join("fifo");
6976        let fifo_c = std::ffi::CString::new(fifo.as_os_str().as_bytes()).unwrap();
6977        assert_eq!(unsafe { libc::mkfifo(fifo_c.as_ptr(), 0o700) }, 0);
6978        let script = write_guest_program(directory.path(), "to-fifo", &shebang_to(&fifo), 0o755);
6979        // A socket cannot be opened at all (ENXIO), and opening a device can
6980        // act on it; both must be refused, not reported as unreadable.
6981        let socket = directory.path().join("socket");
6982        let _listener = std::os::unix::net::UnixListener::bind(&socket).unwrap();
6983        let to_socket =
6984            write_guest_program(directory.path(), "to-socket", &shebang_to(&socket), 0o755);
6985        let device = PathBuf::from("/dev/null");
6986        let to_device =
6987            write_guest_program(directory.path(), "to-device", &shebang_to(&device), 0o755);
6988        // `./fifo` reaches the check through find_program's working-directory
6989        // branch, which does not require a regular file; the scripts reach the
6990        // FIFO, the socket and the device as their interpreters. Nothing opens
6991        // the FIFO for writing, so a blocking open or read would never return:
6992        // each check runs on its own thread and must answer within 10 s.
6993        let cases = [
6994            (
6995                "program",
6996                PathBuf::from("./fifo"),
6997                Some(directory.path().to_owned()),
6998                fs::canonicalize(&fifo).unwrap(),
6999            ),
7000            ("interpreter", script, None, fifo.clone()),
7001            ("socket interpreter", to_socket, None, socket.clone()),
7002            ("device interpreter", to_device, None, device),
7003        ];
7004        for (name, program, current_dir, shown) in cases {
7005            let (sender, receiver) = std::sync::mpsc::channel();
7006            std::thread::spawn(move || {
7007                let mut command = Command::new(&program);
7008                if let Some(directory) = current_dir {
7009                    command.current_dir(directory);
7010                }
7011                let gap = in_guest_liteinst_program_gap(&mut command)
7012                    .map_err(|error| format!("{error:#}"));
7013                let _ = sender.send(gap);
7014            });
7015            let gap = receiver
7016                .recv_timeout(std::time::Duration::from_secs(10))
7017                .unwrap_or_else(|_| panic!("{name}: the check blocked on the FIFO"))
7018                .unwrap()
7019                .unwrap_or_else(|| panic!("{name}: the FIFO was not refused"));
7020            assert!(
7021                gap.contains(&format!("{} is not a regular file", shown.display())),
7022                "{name}: {gap}"
7023            );
7024        }
7025    }
7026
7027    #[test]
7028    #[cfg(feature = "liteinst")]
7029    fn in_guest_liteinst_pins_the_program_the_launch_resolves() {
7030        use interp::startup_fixtures::*;
7031
7032        let directory = tempfile::tempdir().unwrap();
7033        // A name that no host PATH directory holds.
7034        let name = "hermit-3520-static";
7035        let static_elf = write_guest_program(
7036            directory.path(),
7037            name,
7038            &elf(EM_X86_64, &[(PT_LOAD, b"code")]),
7039            0o755,
7040        );
7041        let search = format!("/nonexistent-directory:{}", directory.path().display());
7042        // The launch resolves the program with `find_program` on the command it
7043        // is given. Builds the command twice: once for the launch's own
7044        // resolution, once for the check, which must agree with it.
7045        let check = |build: &dyn Fn() -> Command| {
7046            let launch = build().find_program();
7047            let mut command = build();
7048            let arg0 = command.get_arg0().to_owned();
7049            let gap = in_guest_liteinst_program_gap(&mut command);
7050            match launch {
7051                Ok(program) => {
7052                    let gap = gap.unwrap().expect("the static image was not refused");
7053                    assert!(gap.contains("is statically linked"), "{gap}");
7054                    assert_eq!(Path::new(command.get_program()), program);
7055                    assert_eq!(command.get_arg0(), arg0);
7056                    // Pinned: the launch's own resolution returns it unchanged.
7057                    assert_eq!(command.find_program().unwrap(), program);
7058                    assert_eq!(
7059                        fs::canonicalize(&program).unwrap(),
7060                        fs::canonicalize(&static_elf).unwrap()
7061                    );
7062                    true
7063                }
7064                Err(_) => {
7065                    let error = gap.expect_err("the check found what the launch cannot");
7066                    assert!(
7067                        format!("{error:#}").contains("cannot find guest program"),
7068                        "{error:#}"
7069                    );
7070                    false
7071                }
7072            }
7073        };
7074
7075        // A path with a slash resolves against the guest's working directory.
7076        assert!(check(&|| {
7077            let mut command = Command::new(format!("./{name}"));
7078            command.current_dir(directory.path());
7079            command
7080        }));
7081        // A bare name is searched for in the command's PATH once the base
7082        // environment is cleared, skipping entries without such a file.
7083        assert!(check(&|| {
7084            let mut command = Command::new(name);
7085            command.env_clear().env("PATH", &search);
7086            command
7087        }));
7088        // Without a cleared environment the launch searches Hermit's own PATH,
7089        // not the command's, so the static image is not found by either.
7090        assert!(!check(&|| {
7091            let mut command = Command::new(name);
7092            command.env("PATH", &search);
7093            command
7094        }));
7095        // A cleared environment without PATH (`--base-env=empty`) searches
7096        // Hermit's working directory, not the guest's and not /bin:/usr/bin.
7097        assert!(!check(&|| {
7098            let mut command = Command::new(name);
7099            command.env_clear().current_dir(directory.path());
7100            command
7101        }));
7102        // Not executable, or missing: the launch cannot run it, and neither
7103        // resolution finds it.
7104        fs::set_permissions(&static_elf, fs::Permissions::from_mode(0o644)).unwrap();
7105        assert!(!check(&|| {
7106            let mut command = Command::new(name);
7107            command.env_clear().env("PATH", &search);
7108            command
7109        }));
7110        assert!(!check(&|| Command::new(&static_elf)));
7111        assert!(!check(&|| Command::new("hermit-no-such-program-3520")));
7112    }
7113
7114    #[test]
7115    fn skid_overshoot_error_refuses_a_successful_result() {
7116        let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7117        let _ = reverie::take_skid_overshoot_count();
7118        assert!(take_skid_overshoot_error().is_none());
7119
7120        reverie::record_skid_overshoot();
7121        let error = take_skid_overshoot_error().expect("recorded overshoot must be reported");
7122        assert!(
7123            error
7124                .to_string()
7125                .contains("observed 1 HERMIT_SKID_OVERSHOOT report(s)")
7126        );
7127        assert!(
7128            error
7129                .to_string()
7130                .contains("deterministic execution was not established")
7131        );
7132        assert_eq!(reverie::take_skid_overshoot_count(), 0);
7133    }
7134
7135    #[test]
7136    fn skid_overshoot_report_preserves_success_without_an_overshoot() {
7137        let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7138        let _ = reverie::take_skid_overshoot_count();
7139
7140        let report = SkidOvershootReport::begin(true);
7141        assert_eq!(report.finish(Ok::<_, Error>(7)).unwrap(), 7);
7142        assert_eq!(reverie::take_skid_overshoot_count(), 0);
7143    }
7144
7145    #[test]
7146    fn skid_overshoot_count_can_cross_the_verify_boundary_with_the_output() {
7147        let _lock = SKID_OVERSHOOT_TEST_LOCK.lock().unwrap();
7148        let _ = reverie::take_skid_overshoot_count();
7149
7150        let report = SkidOvershootReport::begin(true);
7151        reverie::record_skid_overshoot();
7152        let (value, count) = report.finish_with_count(Ok::<_, Error>(7)).unwrap();
7153        assert_eq!(value, 7);
7154        assert_eq!(count, 1);
7155        assert_eq!(reverie::take_skid_overshoot_count(), 0);
7156    }
7157
7158    /// ⚠️ THE REGRESSION agent(hermit-007)'s CODEX LANE CAUGHT, PINNED FOR THE
7159    /// SIGNAL BAND. This test fails if the signal half stops being covered; it
7160    /// does NOT prove the predicate can never drift again, because the
7161    /// `122..=127` half is still a hard-coded literal that a future reserved
7162    /// value would fall outside exactly as 130 did.
7163    /// `liteinst_requires_forced_shutdown` hard-coded
7164    /// `Exited(122..=127)`. When the reserved set grew to include the signal
7165    /// band, `Exited(130)` fell outside it and is not `Signaled(_, _)` -- it is a
7166    /// status hermit CHOSE -- so LiteInst skipped the forced shutdown and
7167    /// `clean_up` could wait forever on `handle.await`. A reachable hang,
7168    /// introduced by widening the reserved set in one place and not the other.
7169    ///
7170    /// The 130 and 143 rows are the ones with teeth: revert the predicate to the
7171    /// bare range and they fail.
7172    #[test]
7173    #[cfg(feature = "liteinst")]
7174    fn liteinst_forced_shutdown_covers_every_status_hermit_reserves() {
7175        // The signal band. Not `Signaled`: hermit CHOSE these codes, because a
7176        // namespace init cannot produce a genuine signalled wait status.
7177        assert!(
7178            liteinst_requires_forced_shutdown(ExitStatus::Exited(130)),
7179            "128+SIGINT"
7180        );
7181        assert!(
7182            liteinst_requires_forced_shutdown(ExitStatus::Exited(143)),
7183            "128+SIGTERM"
7184        );
7185        assert!(
7186            liteinst_requires_forced_shutdown(ExitStatus::Exited(129)),
7187            "128+SIGHUP"
7188        );
7189
7190        // The pre-existing reserved band, unchanged.
7191        assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(122)));
7192        assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(125)));
7193        assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(127)));
7194
7195        // A real signal death still forces shutdown.
7196        assert!(liteinst_requires_forced_shutdown(ExitStatus::Signaled(
7197            nix::sys::signal::Signal::SIGKILL,
7198            false
7199        )));
7200
7201        // ⚠️ CONTROLS, so a predicate that simply returned `true` would fail
7202        // this test rather than pass it. An ordinary guest exit must NOT force a
7203        // shutdown; 128 is excluded because there is no signal 0, and 200 is
7204        // above SIGRTMAX so it is a guest's own number.
7205        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(0)));
7206        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(1)));
7207        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
7208        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
7209        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(200)));
7210        // ⚠️ THE BAND EDGES, WHICH THIS TEST STOPPED SHORT OF. It went up to 143
7211        // and then jumped to 200, so `MAX_SIGNO` could shrink from 64 to 15 with
7212        // every row still green -- proved vacuous by agent(hermit-005)'s codex
7213        // lane. 192 is `128 + SIGRTMAX`, the last status in the band; 193 is the
7214        // first outside it. Testing a range in the middle pins nothing at either end.
7215        assert!(
7216            liteinst_requires_forced_shutdown(ExitStatus::Exited(192)),
7217            "128 + SIGRTMAX is still a signal death and must force shutdown"
7218        );
7219        assert!(
7220            !liteinst_requires_forced_shutdown(ExitStatus::Exited(193)),
7221            "above SIGRTMAX the status is the guest's own and must NOT force shutdown"
7222        );
7223    }
7224
7225    /// ⚠️ The bare `NotFound` here was read as a git-worktree bug and cost real
7226    /// investigation time. The message must name the mount namespace, because
7227    /// the directory it is complaining about usually exists on the host.
7228    #[test]
7229    fn a_cwd_under_tmp_is_explained_by_the_container_tmpfs_not_by_a_missing_directory() {
7230        let error = std::io::Error::from(std::io::ErrorKind::NotFound);
7231        let rendered = format!(
7232            "{}",
7233            super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/agent-checkout"), &error)
7234        );
7235        assert!(
7236            rendered.contains("private, empty tmpfs"),
7237            "must name the mechanism: {rendered}"
7238        );
7239        assert!(
7240            rendered.contains("--workdir"),
7241            "must name a way out: {rendered}"
7242        );
7243        assert!(
7244            rendered.contains("/tmp/agent-checkout"),
7245            "must still name the path asked for: {rendered}"
7246        );
7247    }
7248
7249    /// The explanation must NOT be attached to failures it does not explain --
7250    /// an error that volunteers the wrong cause is what produced the original
7251    /// misdiagnosis, in the other direction.
7252    #[test]
7253    fn the_tmpfs_explanation_is_withheld_where_it_does_not_apply() {
7254        let not_found = std::io::Error::from(std::io::ErrorKind::NotFound);
7255        // ⚠️ A CONSTANT ABSOLUTE PATH, NOT ONE READ FROM THE ENVIRONMENT. The only
7256        // property this arm needs is "outside /tmp", and a literal that is outside
7257        // /tmp by construction supplies it without asking the runner anything.
7258        //
7259        // The earlier form wrote a developer-specific home path, which made
7260        // `scripts/check-portable-paths.sh` red on main -- correctly: that gate
7261        // rejects such a path anywhere in a tracked build or run file, tests and
7262        // COMMENTS included, so spelling one out even to explain this would trip
7263        // it. Replacing it by reading $HOME then made the test depend on the
7264        // runner instead: measured by `agent(codex-rev-2641)`, HOME unset, empty,
7265        // relative and /tmp-rooted gave three different fixtures and one failure.
7266        // A unit test that consults the environment is answering a question about
7267        // the environment.
7268        //
7269        // ⚠️ AND NO GUARD IS NEEDED HERE, WHICH IS THE POINT OF USING A CONSTANT.
7270        // The $HOME form carried `assert!(!outside_path.starts_with("/tmp"))` to
7271        // stop a /tmp-rooted HOME making this vacuous. That assertion could never
7272        // fire: the `!outside.contains("tmpfs")` check below sits ABOVE it in
7273        // source order and panics first in exactly that case. It was decorative,
7274        // and an assertion over a compile-time constant would be too, so there is
7275        // none. The fixture cannot drift into /tmp because nothing computes it.
7276        let outside_path = std::path::Path::new("/nonexistent-home/wt");
7277        let outside = format!(
7278            "{}",
7279            super::kvm_cwd_resolution_error(outside_path, &not_found)
7280        );
7281        assert!(!outside.contains("tmpfs"), "not a /tmp path: {outside}");
7282
7283        // `/tmp` itself resolves in the guest -- the mount POINT exists -- so a
7284        // failure there is something else and must not be mislabelled.
7285        let tmp_itself = format!(
7286            "{}",
7287            super::kvm_cwd_resolution_error(std::path::Path::new("/tmp"), &not_found)
7288        );
7289        assert!(!tmp_itself.contains("tmpfs"), "/tmp itself: {tmp_itself}");
7290
7291        // A different errno under /tmp is a different fault (permissions, say).
7292        let denied = std::io::Error::from(std::io::ErrorKind::PermissionDenied);
7293        let other = format!(
7294            "{}",
7295            super::kvm_cwd_resolution_error(std::path::Path::new("/tmp/x"), &denied)
7296        );
7297        assert!(!other.contains("tmpfs"), "not NotFound: {other}");
7298    }
7299
7300    /// A build-flag message must not assert a machine condition it never tested.
7301    ///
7302    /// ⚠️ THIS IS THE FOURTH DIAGNOSTIC TONIGHT THAT NAMED AN UNESTABLISHED CAUSE,
7303    /// after the sigpipe checker, the manifest gate and the LiteInst pidfd error.
7304    /// "DBT support was not included in this build" reads as "this machine cannot
7305    /// run DBT", and cost four or five unnecessary abstentions across the fleet --
7306    /// agents declined to make DBT claims on a box where DynamoRIO is installed
7307    /// and `--features dbt` builds and runs. The absence is a build flag, and the
7308    /// message must say which flag and admit what it did not check.
7309    #[test]
7310    fn an_unbuilt_backend_names_the_flag_and_claims_nothing_about_the_machine() {
7311        let feature_disabled_backends: &[(Backend, &str)] = &[
7312            #[cfg(not(feature = "dbt"))]
7313            (Backend::Dbt, "dbt"),
7314            #[cfg(not(feature = "sabre"))]
7315            (Backend::Sabre, "sabre"),
7316            #[cfg(not(feature = "e9patch"))]
7317            (Backend::E9patch, "e9patch"),
7318            #[cfg(not(feature = "liteinst"))]
7319            (Backend::Liteinst, "liteinst"),
7320            // in-guest-trap is the same runtime behind the same feature.
7321            #[cfg(not(feature = "liteinst"))]
7322            (Backend::InGuestTrap, "liteinst"),
7323        ];
7324
7325        for &(backend, feature) in feature_disabled_backends {
7326            let reason = backend
7327                .unavailable_reason()
7328                .expect("a feature-disabled backend must report why it is unavailable");
7329            assert!(
7330                reason.contains(feature),
7331                "{backend:?}: a build-flag message must name the flag to rebuild with, got: {reason}"
7332            );
7333            assert!(
7334                reason.contains("has not been checked"),
7335                "{backend:?}: a build-flag message must not imply the machine was tested, got: {reason}"
7336            );
7337        }
7338    }
7339
7340    #[cfg(not(feature = "dbt"))]
7341    #[test]
7342    fn dbt_registry_diagnostic_redirects_to_a_source_build() {
7343        let reason = super::dbt_disabled_build_reason("hermit-run");
7344        assert!(reason.contains("not included in this registry release"));
7345        assert!(reason.contains("source build from https://github.com/rrnewton/hermit"));
7346        assert!(reason.contains("`third-party-backends` feature does not include DBT"));
7347        assert!(reason.contains("has not been checked"));
7348
7349        let source_reason = super::dbt_disabled_build_reason("hermit");
7350        assert!(source_reason.contains("rebuild with `--features dbt`"));
7351        assert!(!source_reason.contains("not included in this registry release"));
7352    }
7353
7354    #[cfg(not(feature = "sabre"))]
7355    #[tokio::test]
7356    async fn disabled_sabre_dispatch_refuses_before_resolving_the_program() {
7357        let program = "/hermit-missing-disabled-sabre-program";
7358        let error = super::dispatch_backend(
7359            super::Command::new(program),
7360            super::DetConfig::default(),
7361            false,
7362            &None,
7363            Backend::Sabre,
7364            None,
7365        )
7366        .await
7367        .unwrap_err();
7368        assert!(
7369            error
7370                .to_string()
7371                .contains("the `sabre` feature is not enabled")
7372        );
7373        let error = super::dispatch_output_backend(
7374            super::Command::new(program),
7375            super::DetConfig::default(),
7376            false,
7377            &None,
7378            Backend::Sabre,
7379            None,
7380        )
7381        .await
7382        .unwrap_err();
7383        assert!(
7384            error
7385                .to_string()
7386                .contains("the `sabre` feature is not enabled")
7387        );
7388    }
7389
7390    #[test]
7391    #[cfg(feature = "dbt")]
7392    fn a_cold_dbt_runtime_diagnostic_is_not_feature_absence() {
7393        let reason = dbt_runtime_unavailable_reason_from(Err(io::Error::new(
7394            io::ErrorKind::NotFound,
7395            "Hermit DBT runtime was not built beside /cold-target/hermit or in its deps directory",
7396        )))
7397        .expect("a missing cold-target runtime must remain unavailable");
7398
7399        assert!(reason.contains("was not built beside"));
7400        assert!(reason.contains("build the hermit binary and cdylib"));
7401        assert!(!reason.contains("not enabled in this build"));
7402        assert!(!reason.contains("has not been checked"));
7403    }
7404    #[cfg(feature = "sabre")]
7405    use std::ffi::OsStr;
7406    use std::fs;
7407    #[cfg(feature = "sabre")]
7408    use std::os::unix::fs::PermissionsExt;
7409    use std::path::PathBuf;
7410    #[cfg(feature = "sabre")]
7411    use std::sync::Arc;
7412    #[cfg(feature = "sabre")]
7413    use std::time::Duration;
7414
7415    use super::Backend;
7416    #[cfg(any(feature = "sabre", feature = "liteinst"))]
7417    use super::ExitStatus;
7418    use super::HermitData;
7419    use super::Id;
7420    #[cfg(feature = "sabre")]
7421    use super::SABRE_RPC_SOCKET_ENV;
7422    use super::collect_recording_ids;
7423    #[cfg(feature = "dbt")]
7424    use super::dbt_runtime_unavailable_reason;
7425    #[cfg(feature = "dbt")]
7426    use super::dbt_runtime_unavailable_reason_from;
7427    #[cfg(feature = "dbt")]
7428    use super::dynamorio_sdk_available;
7429    use super::ensure_backend_dispatch;
7430    #[cfg(feature = "dbt")]
7431    use super::is_dynamorio_sdk;
7432    use super::kvm_device_unavailable_reason;
7433    #[cfg(feature = "liteinst")]
7434    use super::liteinst_requires_forced_shutdown;
7435    #[cfg(feature = "dbt")]
7436    use super::liteinst_unavailable_reason;
7437    use super::output_backend_stdin_file;
7438    use super::prepare_backend_config;
7439    use super::reserve_output_stdin_snapshot;
7440    use super::resolve_kvm_shebang;
7441    #[cfg(feature = "sabre")]
7442    use super::resolve_sabre_binary_from;
7443    #[cfg(feature = "sabre")]
7444    use super::sabre_backend_evidence_line;
7445    #[cfg(feature = "sabre")]
7446    use super::sabre_program_needs_neutral_name;
7447    #[cfg(feature = "sabre")]
7448    use super::sabre_reach_state;
7449    #[cfg(feature = "sabre")]
7450    use super::sabre_uninstrumented_guest_message;
7451    #[cfg(feature = "sabre")]
7452    use super::shutdown_sabre_rpc;
7453    #[cfg(feature = "sabre")]
7454    use super::stage_sabre_program_in;
7455    #[cfg(feature = "sabre")]
7456    use super::stop_sabre_rpc_server;
7457    #[cfg(feature = "sabre")]
7458    use super::wait_for_sabre_rpc_disconnects;
7459
7460    #[test]
7461    fn recording_inventory_preserves_missing_and_non_recording_cases() {
7462        let parent = tempfile::tempdir().expect("failed to create recording inventory parent");
7463        let missing = parent.path().join("missing");
7464        assert!(
7465            HermitData::with_dir(&missing)
7466                .try_recordings()
7467                .expect("a missing data directory should be empty")
7468                .is_empty()
7469        );
7470
7471        let inventory = parent.path().join("inventory");
7472        fs::create_dir(&inventory).expect("failed to create recording inventory");
7473        let recording: Id = "0123456789abcdef0123456789abcdef"
7474            .parse()
7475            .expect("valid recording ID");
7476        fs::create_dir(inventory.join(recording.to_string()))
7477            .expect("failed to create recording directory");
7478        fs::create_dir(inventory.join("not-a-recording"))
7479            .expect("failed to create invalid-name directory");
7480        fs::write(
7481            inventory.join("fedcba9876543210fedcba9876543210"),
7482            b"not a directory",
7483        )
7484        .expect("failed to create valid-looking non-directory");
7485
7486        assert_eq!(
7487            HermitData::with_dir(&inventory)
7488                .try_recordings()
7489                .expect("recording inventory should be readable"),
7490            vec![recording]
7491        );
7492        assert_eq!(
7493            HermitData::with_dir(&inventory)
7494                .recordings()
7495                .collect::<Vec<_>>(),
7496            vec![recording]
7497        );
7498    }
7499
7500    #[test]
7501    fn recording_inventory_rejects_an_error_after_a_valid_entry() {
7502        let inventory = tempfile::tempdir().expect("failed to create recording inventory");
7503        let recording: Id = "0123456789abcdef0123456789abcdef"
7504            .parse()
7505            .expect("valid recording ID");
7506        fs::create_dir(inventory.path().join(recording.to_string()))
7507            .expect("failed to create recording directory");
7508        let valid_entry = fs::read_dir(inventory.path())
7509            .expect("failed to open recording inventory")
7510            .next()
7511            .expect("missing recording entry")
7512            .expect("failed to read recording entry");
7513
7514        let entries = vec![
7515            Ok(valid_entry),
7516            Err(std::io::Error::other("injected entry failure")),
7517        ];
7518        let error = collect_recording_ids(entries, inventory.path(), fs::DirEntry::file_type)
7519            .expect_err("a partial inventory must not be returned");
7520        assert!(
7521            error
7522                .to_string()
7523                .contains("Failed to read an entry in recording inventory"),
7524            "unexpected error: {error:#}"
7525        );
7526    }
7527
7528    #[test]
7529    fn recording_inventory_rejects_an_entry_inspection_error() {
7530        let inventory = tempfile::tempdir().expect("failed to create recording inventory");
7531        let recording = inventory.path().join("0123456789abcdef0123456789abcdef");
7532        fs::create_dir(&recording).expect("failed to create recording directory");
7533        let entry = fs::read_dir(inventory.path())
7534            .expect("failed to open recording inventory")
7535            .next()
7536            .expect("missing recording entry")
7537            .expect("failed to read recording entry");
7538
7539        let error = collect_recording_ids([Ok(entry)], inventory.path(), |_| {
7540            Err(std::io::Error::other("injected inspection failure"))
7541        })
7542        .expect_err("an uninspectable entry must fail the inventory");
7543        assert!(
7544            error
7545                .to_string()
7546                .contains("Failed to inspect recording inventory entry"),
7547            "unexpected error: {error:#}"
7548        );
7549    }
7550
7551    /// Regression test for the `hermit run --verify` empty-stdin bug: a pipe
7552    /// (non-seekable) fed to hermit must be buffered and replayed *identically*
7553    /// to every run of `--verify`. Before the fix the output-capturing backend
7554    /// used `Stdio::null()`, so piped input was silently dropped and both runs
7555    /// saw empty input (a false "deterministic" pass, e.g. `gcc -x c -`
7556    /// compiling nothing). This asserts the reserved snapshot replays the exact
7557    /// bytes twice.
7558    #[test]
7559    fn output_stdin_snapshot_replays_pipe_to_repeated_runs() {
7560        use std::io::Read;
7561        use std::io::Write;
7562        use std::os::fd::FromRawFd;
7563
7564        // A pipe is non-seekable, exercising the buffer-into-tempfile path that
7565        // matches the real `echo prog | hermit run --verify` scenario.
7566        let mut fds = [0i32; 2];
7567        assert_eq!(unsafe { libc::pipe(fds.as_mut_ptr()) }, 0);
7568        // SAFETY: pipe(2) just returned two fresh owned descriptors.
7569        let read_end = unsafe { fs::File::from_raw_fd(fds[0]) };
7570        let mut write_end = unsafe { fs::File::from_raw_fd(fds[1]) };
7571
7572        let payload = b"int main(){return 0;}\n";
7573        write_end.write_all(payload).unwrap();
7574        // Close the write end so draining the pipe hits EOF.
7575        drop(write_end);
7576
7577        reserve_output_stdin_snapshot(Some(read_end)).unwrap();
7578
7579        // Two successive runs (as `--verify` performs) must each read the full
7580        // payload from the start.
7581        for run in 0..2 {
7582            let mut file = output_backend_stdin_file()
7583                .unwrap()
7584                .unwrap_or_else(|| panic!("run {run}: expected a replayable stdin snapshot"));
7585            let mut got = Vec::new();
7586            file.read_to_end(&mut got).unwrap();
7587            assert_eq!(got, payload, "run {run} stdin replay mismatch");
7588        }
7589
7590        let mut file = output_backend_stdin_file().unwrap().unwrap();
7591        let error = file
7592            .write_all(b"guest-must-not-change-the-snapshot")
7593            .expect_err("the replayed stdin must be read-only");
7594        assert_eq!(error.raw_os_error(), Some(libc::EBADF));
7595    }
7596
7597    #[test]
7598    #[cfg(feature = "liteinst")]
7599    fn liteinst_reserved_failures_require_scheduler_cancellation() {
7600        for status in 122..=127 {
7601            assert!(liteinst_requires_forced_shutdown(ExitStatus::Exited(
7602                status
7603            )));
7604        }
7605        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(121)));
7606        assert!(!liteinst_requires_forced_shutdown(ExitStatus::Exited(128)));
7607    }
7608
7609    /// A SaBRe guest that never reaches the coordinator ran with no Detcore in
7610    /// the loop at all. The diagnosis must say so in those terms -- a
7611    /// zero-syscall SaBRe run is not a weak result, it is *no* result -- and it
7612    /// must name the statically linked ELF case, which is the shape that
7613    /// reaches this path in practice because a static client has no dynamic
7614    /// loader through which SaBRe could regain control.
7615    #[test]
7616    #[cfg(feature = "sabre")]
7617    fn uninstrumented_sabre_guest_is_reported_as_no_determinization() {
7618        let message = sabre_uninstrumented_guest_message(&ExitStatus::Exited(0));
7619        assert!(
7620            message.contains("no determinization at all"),
7621            "must not present an uninstrumented run as a weaker guarantee: {message}"
7622        );
7623        assert!(
7624            message.contains("Detcore coordinator"),
7625            "must name the authority that was never reached: {message}"
7626        );
7627        assert!(
7628            message.contains("statically linked ELF"),
7629            "must name the dominant cause so the reader can act: {message}"
7630        );
7631        // The exit status is carried because a successful-looking status is
7632        // exactly what makes this failure mode dangerous.
7633        assert!(
7634            message.contains("Exited(0)"),
7635            "must carry the observed status: {message}"
7636        );
7637        assert!(
7638            sabre_uninstrumented_guest_message(&ExitStatus::Exited(139)).contains("Exited(139)"),
7639            "must carry a failing status too"
7640        );
7641    }
7642
7643    /// The old two-way banner treated both `guest_rpc_observed=false` and an
7644    /// engaged zero-fallback run as `sabre-exercised`. Assert the three states
7645    /// together so no pair can collapse back onto one value.
7646    #[test]
7647    #[cfg(feature = "sabre")]
7648    fn sabre_reach_states_are_pairwise_distinct() {
7649        let no_detcore = sabre_reach_state(false, 0);
7650        let degraded = sabre_reach_state(true, 1);
7651        let exercised = sabre_reach_state(true, 0);
7652
7653        assert_eq!(no_detcore, "no-detcore-reached");
7654        assert_eq!(degraded, "degraded-ptrace-fallback");
7655        assert_eq!(exercised, "sabre-exercised");
7656        assert_ne!(no_detcore, degraded);
7657        assert_ne!(no_detcore, exercised);
7658        assert_ne!(degraded, exercised);
7659        assert_eq!(
7660            sabre_reach_state(false, 9),
7661            "no-detcore-reached",
7662            "absence of a guest RPC must dominate any fallback count"
7663        );
7664    }
7665
7666    #[test]
7667    #[cfg(feature = "sabre")]
7668    fn sabre_backend_fact_is_versioned_and_names_preplugin_coverage() {
7669        let exercised = super::sabre_ptrace::PathEvidence {
7670            schema: 1,
7671            guest_rpc_observed: true,
7672            ptrace_fallback_sites: 0,
7673            trusted_shared_object_sites: 2,
7674            trusted_shared_objects: vec!["/usr/lib/libc.so.6".to_owned()],
7675        };
7676        assert_eq!(
7677            sabre_backend_evidence_line(&exercised),
7678            ":: Backend: sabre static rewriting + ptrace runtime; run_mode=run; \
7679             evidence_schema=1; preplugin_coverage=absent; ptrace_fallback_sites=0; \
7680             trusted_shared_object_sites=2; guest_rpc_observed=true; \
7681             reach_state=sabre-exercised"
7682        );
7683
7684        let unengaged = super::sabre_ptrace::PathEvidence {
7685            guest_rpc_observed: false,
7686            ..exercised
7687        };
7688        let fact = sabre_backend_evidence_line(&unengaged);
7689        assert!(fact.contains("preplugin_coverage=absent"));
7690        assert!(fact.contains("reach_state=no-detcore-reached"));
7691        assert!(!fact.contains("reach_state=sabre-exercised"));
7692    }
7693
7694    #[test]
7695    fn liteinst_backend_config_preserves_the_requested_timeslice() {
7696        // Configuration must not silently clear a requested timeslice: the
7697        // in-guest LiteInst refusal relies on seeing it.
7698        let config = super::DetConfig::default();
7699        assert!(config.max_timeslice.is_some());
7700        for backend in [Backend::Liteinst, Backend::InGuestTrap] {
7701            assert!(
7702                prepare_backend_config(config.clone(), backend)
7703                    .max_timeslice
7704                    .is_some(),
7705                "{backend:?}"
7706            );
7707        }
7708        assert!(
7709            prepare_backend_config(config, Backend::Ptrace)
7710                .max_timeslice
7711                .is_some()
7712        );
7713    }
7714
7715    #[test]
7716    fn in_guest_liteinst_cancels_killed_thread_rpcs() {
7717        let config = super::DetConfig::default();
7718        for backend in [Backend::Liteinst, Backend::InGuestTrap] {
7719            assert!(
7720                prepare_backend_config(config.clone(), backend)
7721                    .backend
7722                    .needs_killed_thread_rpc_cancellation,
7723                "{backend:?}"
7724            );
7725        }
7726        // LiteInst's cancellation changes no other backend.
7727        assert!(
7728            !prepare_backend_config(config, Backend::Ptrace)
7729                .backend
7730                .needs_killed_thread_rpc_cancellation
7731        );
7732    }
7733
7734    #[test]
7735    fn sabre_backend_configures_process_local_capabilities() {
7736        let config = super::DetConfig::default();
7737        let sabre = prepare_backend_config(config.clone(), Backend::Sabre).backend;
7738        assert!(sabre.tool_shares_guest_descriptor_table);
7739        assert!(sabre.rediscovers_descriptors_after_exec);
7740        assert!(sabre.internal_pipe_turns_are_host_timed);
7741        assert!(sabre.loopback_pollers_yield_to_peers);
7742        assert!(sabre.guest_clock_reads_bypass_backend);
7743        assert!(sabre.virtualizes_syscall_clobbers);
7744        assert!(sabre.needs_killed_thread_rpc_cancellation);
7745        assert!(sabre.reports_physical_process_exits);
7746        assert!(sabre.signal_interrupts_external_syscalls);
7747        assert!(sabre.tracks_process_children);
7748        assert!(!sabre.runs_exit_robust_list);
7749        assert!(!sabre.requires_thread_directed_process_signals);
7750        assert!(!sabre.defers_vfork_child_registration);
7751        let ptrace = prepare_backend_config(config, Backend::Ptrace).backend;
7752        assert!(!ptrace.tool_shares_guest_descriptor_table);
7753        assert!(!ptrace.rediscovers_descriptors_after_exec);
7754        assert!(!ptrace.internal_pipe_turns_are_host_timed);
7755        assert!(!ptrace.loopback_pollers_yield_to_peers);
7756        assert!(!ptrace.guest_clock_reads_bypass_backend);
7757        assert!(!ptrace.virtualizes_syscall_clobbers);
7758        assert!(!ptrace.needs_killed_thread_rpc_cancellation);
7759        assert!(!ptrace.reports_physical_process_exits);
7760        assert!(!ptrace.signal_interrupts_external_syscalls);
7761        assert!(ptrace.tracks_process_children);
7762        assert!(ptrace.runs_exit_robust_list);
7763        assert!(!ptrace.requires_thread_directed_process_signals);
7764        assert!(!ptrace.defers_vfork_child_registration);
7765    }
7766
7767    #[test]
7768    fn kvm_reports_stored_metadata_timestamps_only_for_sequential_tool_threads() {
7769        let sequential = prepare_backend_config(
7770            super::DetConfig {
7771                sequentialize_threads: true,
7772                virtualize_metadata: true,
7773                ..super::DetConfig::default()
7774            },
7775            Backend::Kvm,
7776        );
7777        assert!(super::kvm_reports_stored_metadata_timestamps(&sequential));
7778
7779        // Another guest thread could read the stored values before Detcore
7780        // rewrites them.
7781        let concurrent = super::DetConfig {
7782            sequentialize_threads: false,
7783            ..sequential.clone()
7784        };
7785        assert!(!super::kvm_reports_stored_metadata_timestamps(&concurrent));
7786
7787        // Nothing rewrites the stored values.
7788        let host_metadata = super::DetConfig {
7789            virtualize_metadata: false,
7790            ..sequential
7791        };
7792        assert!(!super::kvm_reports_stored_metadata_timestamps(
7793            &host_metadata
7794        ));
7795    }
7796
7797    #[test]
7798    fn kvm_backend_config_marks_concurrent_process_children() {
7799        let defaults = super::DetConfig::default();
7800        assert!(!defaults.sequentialize_threads);
7801        let nonsequential = prepare_backend_config(defaults, Backend::Kvm);
7802        assert!(nonsequential.backend.provides_process_signal_control);
7803        assert!(nonsequential.backend.emulates_child_waits);
7804        assert!(!may_observe_signal_dequeues(&nonsequential));
7805        assert!(!requires_signal_control(&nonsequential));
7806
7807        let config = super::DetConfig {
7808            sequentialize_threads: true,
7809            ..super::DetConfig::default()
7810        };
7811        let kvm = prepare_backend_config(config, Backend::Kvm);
7812        assert!(may_observe_signal_dequeues(&kvm));
7813        assert!(requires_signal_control(&kvm));
7814        assert!(kvm.backend.needs_killed_thread_rpc_cancellation);
7815        assert!(kvm.backend.tracks_process_children);
7816        assert!(!kvm.backend.runs_exit_robust_list);
7817        assert!(!kvm.backend.requires_thread_directed_process_signals);
7818        assert!(kvm.backend.defers_vfork_child_registration);
7819
7820        // A controlled run needs both the backend's process-signal control and
7821        // sequentialized threads; neither alone admits one.
7822        for backend in [
7823            Backend::Ptrace,
7824            Backend::Dbt,
7825            Backend::Sabre,
7826            Backend::Liteinst,
7827            Backend::InGuestTrap,
7828            Backend::E9patch,
7829        ] {
7830            let config = super::DetConfig {
7831                sequentialize_threads: true,
7832                ..super::DetConfig::default()
7833            };
7834            let prepared = prepare_backend_config(config, backend);
7835            assert!(!may_observe_signal_dequeues(&prepared), "{backend:?}");
7836            assert!(!requires_signal_control(&prepared), "{backend:?}");
7837        }
7838    }
7839
7840    /// Whether Detcore asks the backend to install process signal control for
7841    /// `config`: the bound Reverie checks before it offers the control.
7842    fn may_observe_signal_dequeues(config: &DetConfig) -> bool {
7843        <super::Detcore as reverie::Tool>::may_observe_signal_dequeues(config)
7844    }
7845
7846    /// Whether Reverie must refuse `config` on a runner that offers no
7847    /// process signal control, as Detcore's installation did before.
7848    fn requires_signal_control(config: &DetConfig) -> bool {
7849        <super::Detcore as reverie::Tool>::requires_signal_control(config)
7850    }
7851
7852    /// The values the hand-written assignments in `prepare_backend_config` and
7853    /// `run_kvm` gave each backend before Detcore read
7854    /// [`reverie::BackendCapabilities`], transcribed field by field. A backend
7855    /// identity check became the capability it selected:
7856    /// `discover_live_file_metadata` split into the first four fields, the old
7857    /// `backend_reports_physical_process_exits` became two, and
7858    /// `backend_is_kvm` became five, of which the last two remain here:
7859    /// `refuses_nonleader_exec_with_enosys` became the backend's typed exec
7860    /// refusal (Reverie d78f770f), `failed_gettimeofday_may_store_host_time`
7861    /// the guest's storable-memory report (Reverie 8bfb450e) and
7862    /// `user_address_limit` the guest's user address limit query (Reverie
7863    /// 6f75cc4c). Four fields are newer than that transcription:
7864    /// `process_exits_complete_asynchronously` (Reverie 056c8cac), true only
7865    /// for in-guest LiteInst, whose process exits complete some time after the
7866    /// tool grants them, `supports_madv_dontneed` (Reverie 8d8697aa), true for
7867    /// every backend, and `reports_child_exit_publication` (Reverie 9cb6f7b7),
7868    /// true for ptrace and e9patch, whose tracer reports when the kernel
7869    /// publishes a process's exit to its parent, and
7870    /// `virtualizes_guest_sigalrm` (Reverie 7142ff8c), true only for in-guest
7871    /// LiteInst, whose runtime keeps a guest SIGALRM handler virtual (signal
7872    /// phase 1). `in-guest-trap` is in-guest LiteInst with site patching off,
7873    /// which changes how a syscall reaches the Tool and nothing the Tool host
7874    /// can do, so it has exactly in-guest LiteInst's row.
7875    /// DBT now also shares the guest descriptor table and rediscovers it after
7876    /// exec (Reverie 15374907); its host-timed-turn and poller-yield
7877    /// capabilities remain false. `reports_sigreturns` (A5 step 2) is true
7878    /// for ptrace, and so for e9patch preprocessing, whose guest Hermit runs
7879    /// on ptrace. `reports_kernel_child_exit_signals` is true for ptrace,
7880    /// e9patch and SaBRe, whose signal callbacks see the kernel's child-exit
7881    /// SIGCHLD with its siginfo and can suppress or rewrite it.
7882    fn golden_backend_capabilities(backend: Backend) -> serde_json::Value {
7883        let sabre = backend == Backend::Sabre;
7884        let kvm = backend == Backend::Kvm;
7885        let dbt = backend == Backend::Dbt;
7886        // LiteInst runs only through its in-guest runtime.
7887        let in_guest_liteinst = matches!(backend, Backend::Liteinst | Backend::InGuestTrap);
7888        serde_json::json!({
7889            "tool_shares_guest_descriptor_table": sabre || dbt,
7890            "rediscovers_descriptors_after_exec": sabre || dbt,
7891            "internal_pipe_turns_are_host_timed": sabre,
7892            "loopback_pollers_yield_to_peers": sabre,
7893            "guest_clock_reads_bypass_backend": sabre,
7894            "virtualizes_syscall_clobbers": sabre,
7895            "needs_killed_thread_rpc_cancellation": in_guest_liteinst || sabre || dbt || kvm,
7896            "reports_physical_process_exits": sabre,
7897            "process_exits_complete_asynchronously": in_guest_liteinst,
7898            "virtualizes_guest_sigalrm": in_guest_liteinst,
7899            "signal_interrupts_external_syscalls": sabre,
7900            "tracks_process_children": !dbt,
7901            "runs_exit_robust_list": matches!(backend, Backend::Ptrace | Backend::E9patch),
7902            "requires_thread_directed_process_signals": dbt,
7903            "supports_parked_write_signal_interruption":
7904                matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Kvm),
7905            "defers_vfork_child_registration": kvm,
7906            "supports_madvise": !kvm,
7907            "supports_madv_dontneed": true,
7908            "reports_child_exit_publication":
7909                matches!(backend, Backend::Ptrace | Backend::E9patch),
7910            "reports_kernel_child_exit_signals":
7911                matches!(backend, Backend::Ptrace | Backend::E9patch | Backend::Sabre),
7912            "provides_process_signal_control": kvm,
7913            "emulates_child_waits": kvm,
7914            // A Config field Hermit set from the backend's name before it was
7915            // a stated capability. e9patch runs on ptrace and has its value.
7916            "supports_blocked_wait_signal_interruption":
7917                matches!(backend, Backend::Ptrace | Backend::E9patch),
7918            "delivers_preemption_timer_events":
7919                matches!(backend, Backend::Ptrace | Backend::E9patch),
7920            "runs_guest_code_between_injections": sabre || in_guest_liteinst,
7921            "promotes_open_files_before_native_lifecycle": dbt || in_guest_liteinst,
7922            // Hermit runs e9patch preprocessing as a ptrace run (empty
7923            // trampolines keep the original syscall instruction), whose
7924            // rt_sigreturns reach the seccomp stop that reports them.
7925            "reports_sigreturns": matches!(backend, Backend::Ptrace | Backend::E9patch),
7926        })
7927    }
7928
7929    #[test]
7930    fn backend_capabilities_match_the_golden_table() {
7931        for backend in [
7932            Backend::Ptrace,
7933            Backend::Kvm,
7934            Backend::E9patch,
7935            Backend::Liteinst,
7936            Backend::InGuestTrap,
7937            Backend::Sabre,
7938            Backend::Dbt,
7939        ] {
7940            let config = prepare_backend_config(super::DetConfig::default(), backend);
7941            assert_eq!(
7942                serde_json::to_value(config.backend).unwrap(),
7943                golden_backend_capabilities(backend),
7944                "{backend:?}"
7945            );
7946        }
7947    }
7948
7949    #[test]
7950    fn backend_capabilities_are_the_ones_each_backend_reports() {
7951        assert_eq!(
7952            super::backend_capabilities(Backend::Ptrace),
7953            <reverie_ptrace::PtraceBackend as reverie::Backend>::capabilities()
7954        );
7955        assert_eq!(
7956            super::backend_capabilities(Backend::Kvm),
7957            reverie_kvm::KvmBackend::capabilities()
7958        );
7959        #[cfg(feature = "liteinst")]
7960        {
7961            // SAFETY: the strong immutable declaration above has the public
7962            // repr(C), two-u64 descriptor ABI. This reads the real linked
7963            // object, so changing the host declaration to Fixed fails here.
7964            let backing = unsafe {
7965                std::ptr::addr_of!(super::reverie_liteinst_allocator_backing_v1)
7966                    .cast::<[u64; 2]>()
7967                    .read_volatile()
7968            };
7969            assert_eq!(backing, [1, 1], "host Hermit must declare Legacy backing");
7970            assert_eq!(
7971                super::backend_capabilities(Backend::Liteinst),
7972                <reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
7973            );
7974            // in-guest-trap runs the same Reverie backend.
7975            assert_eq!(
7976                super::backend_capabilities(Backend::InGuestTrap),
7977                <reverie_liteinst::LiteinstBackend as reverie::Backend>::capabilities()
7978            );
7979        }
7980        #[cfg(feature = "dbt")]
7981        {
7982            assert_eq!(
7983                super::backend_capabilities(Backend::Dbt),
7984                reverie_dbt::DbtRunner::capabilities()
7985            );
7986            // The DBT runtime re-asserts the same value when it loads the
7987            // configuration this crate serializes for it.
7988            assert_eq!(
7989                super::backend_capabilities(Backend::Dbt),
7990                detcore_dbt::backend_capabilities()
7991            );
7992        }
7993    }
7994
7995    /// `Config` with its three environment-backed fields (`HERMIT_EPOCH`,
7996    /// `HERMIT_PRNG`, `HERMIT_SCHED_SEED`) pinned, so the encoding does not
7997    /// depend on the test process's environment.
7998    fn env_free_detconfig(epoch: &str, seed: &str) -> DetConfig {
7999        use clap::Parser;
8000        let mut config = DetConfig::parse_from(["hermit", epoch, seed, "--sched-seed=0"]);
8001        config.sched_seed = None;
8002        config
8003    }
8004
8005    /// Non-default values in fields that serialize as strings, floats,
8006    /// options and nested arrays. The path contains legacy key names, so an
8007    /// encoder that edited text would put a key inside a string value.
8008    fn rich_detconfig() -> DetConfig {
8009        let mut config = env_free_detconfig("--epoch=2000-12-31T23:59:59Z", "--seed=7");
8010        config.rng_seed = Some(13);
8011        config.sched_seed = Some(11);
8012        config.clock_multiplier = Some(1.5);
8013        config.chaos = true;
8014        config.record_preemptions_to = Some(std::path::PathBuf::from(
8015            "/tmp/a,\"detect_host_clock_futex_timeouts\":true,\"backend_tracks_process_children\":{",
8016        ));
8017        config.mountinfo_root_rewrites = vec![detcore_model::config::MountInfoRootRewrite {
8018            raw_mount_id: 41,
8019            deterministic_root: b"/".to_vec(),
8020            raw_root_prefix: Some(b"/tmp/x".to_vec()),
8021            deterministic_root_prefix: Some(b"/tmp".to_vec()),
8022            raw_mountpoint_prefix: None,
8023            deterministic_mountpoint_prefix: None,
8024        }];
8025        config.stacktrace_event = vec![(3, Some(std::path::PathBuf::from("/s")))];
8026        config
8027    }
8028
8029    /// `HERMIT_DBT_DETCONFIG` is in the guest's environment, so a guest can
8030    /// read it with `getenv` or `/proc/self/environ`. These fixtures are the
8031    /// output of `serde_json::to_string` on the same configs, captured from a
8032    /// build of the commit before Detcore read [`reverie::BackendCapabilities`],
8033    /// when `Config` still had one boolean field per backend switch. They are
8034    /// the variable's bytes before `dbt_detconfig_json` re-inserts the three
8035    /// deleted switches' keys; `dbt_detconfig_matches_806cf2fa_bytes` pins the
8036    /// complete variable. Every DBT run sequentializes threads, so the DBT
8037    /// cases do too. The fixtures carry one deliberate later change, the
8038    /// `fdinfo_unlisted_mount_ids` -> `mount_id_assignment_order` key rename
8039    /// described on `dbt_detconfig_tests::GOLDEN`. Preserve the historical DBT
8040    /// descriptor capabilities here as well as the historical bytes. Current
8041    /// DBT's independent descriptor facts require the typed envelope, whose
8042    /// exact round trip and all sixteen coupled-flag combinations are checked
8043    /// by `dbt_detconfig_tests`.
8044    #[test]
8045    fn historical_dbt_capabilities_preserve_legacy_detconfig_bytes() {
8046        let sequential = |mut config: DetConfig| {
8047            config.sequentialize_threads = true;
8048            config
8049        };
8050        let default_config = || env_free_detconfig("--epoch=2026-01-01T00:00:00Z", "--seed=0");
8051        for (name, mut config, before) in [
8052            (
8053                "default",
8054                default_config(),
8055                include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-default.json"),
8056            ),
8057            (
8058                "dbt",
8059                prepare_backend_config(sequential(default_config()), Backend::Dbt),
8060                include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-dbt.json"),
8061            ),
8062            (
8063                "rich_dbt",
8064                prepare_backend_config(sequential(rich_detconfig()), Backend::Dbt),
8065                include_str!("../tests/fixtures/dbt/detconfig-before-capabilities-rich_dbt.json"),
8066            ),
8067        ] {
8068            config.backend.tool_shares_guest_descriptor_table = false;
8069            config.backend.rediscovers_descriptors_after_exec = false;
8070            // Read back as false, as the `Config` fields they replace were.
8071            config.backend.supports_blocked_wait_signal_interruption = false;
8072            config.backend.delivers_preemption_timer_events = false;
8073            config.backend.runs_guest_code_between_injections = false;
8074            assert_eq!(
8075                detcore::to_legacy_backend_json(&config).unwrap(),
8076                before,
8077                "HERMIT_DBT_DETCONFIG for the {name} config changed"
8078            );
8079            // A reader of the earlier bytes recovers the capabilities.
8080            let decoded = detcore::from_legacy_backend_json(before).unwrap();
8081            assert_eq!(decoded.backend, config.backend, "{name}");
8082            assert_eq!(
8083                decoded.sequentialize_threads, config.sequentialize_threads,
8084                "{name}"
8085            );
8086            assert_eq!(
8087                detcore::to_legacy_backend_json(&decoded).unwrap(),
8088                before,
8089                "{name}"
8090            );
8091        }
8092    }
8093
8094    /// The fifteen per-backend keys, in the order the encoding has always
8095    /// carried them.
8096    const LEGACY_BACKEND_KEYS: [&str; 15] = [
8097        "cpuid_virtualized_by_backend",
8098        "backend_supports_madvise",
8099        "discover_live_file_metadata",
8100        "detect_host_clock_futex_timeouts",
8101        "syscall_clobbers_virtualized_by_backend",
8102        "cancel_killed_thread_rpcs",
8103        "backend_reports_physical_process_exits",
8104        "backend_tracks_process_children",
8105        "backend_runs_exit_robust_list",
8106        "backend_requires_thread_directed_process_signals",
8107        "backend_is_kvm",
8108        "kvm_shared_dequeue_timers",
8109        "backend_supports_parked_write_signal_interruption",
8110        "backend_virtualizes_capability_prctls",
8111        "backend_defers_vfork_child_registration",
8112    ];
8113
8114    /// Pin the current projection onto all fifteen legacy backend keys, once
8115    /// without and once with sequentialized threads. DBT's two descriptor
8116    /// facts project to `discover_live_file_metadata=true`; that legacy bit
8117    /// cannot retain their independence from the host-timed capabilities.
8118    /// Current DBT therefore uses the separately checked typed envelope, not
8119    /// this lossy projection. LiteInst's row is its in-guest runtime. KVM's
8120    /// first two digits are the capabilities `run_kvm` formerly set itself; the
8121    /// first, `cpuid_virtualized_by_backend`, is written false for every
8122    /// backend now that no backend installs a CPUID profile of its own, and so
8123    /// is the fourteenth, `backend_virtualizes_capability_prctls`, now that
8124    /// the capability prctls reach the kernel on every backend.
8125    #[test]
8126    fn every_backend_encodes_its_current_legacy_projection() {
8127        for (backend, unsequenced, sequential) in [
8128            (Backend::Ptrace, "010000011000100", "010000011000100"),
8129            (Backend::E9patch, "010000011000100", "010000011000100"),
8130            (Backend::Liteinst, "010001010000000", "010001010000000"),
8131            (Backend::InGuestTrap, "010001010000000", "010001010000000"),
8132            (Backend::Sabre, "011111110000000", "011111110000000"),
8133            (Backend::Dbt, "011001000100000", "011001000100000"),
8134            (Backend::Kvm, "000001010010101", "000001010011101"),
8135        ] {
8136            for (sequentialize_threads, expected) in [(false, unsequenced), (true, sequential)] {
8137                let config = prepare_backend_config(
8138                    DetConfig {
8139                        sequentialize_threads,
8140                        ..DetConfig::default()
8141                    },
8142                    backend,
8143                );
8144                let encoded: serde_json::Map<String, serde_json::Value> =
8145                    serde_json::from_str(&detcore::to_legacy_backend_json(&config).unwrap())
8146                        .unwrap();
8147                let digits: String = LEGACY_BACKEND_KEYS
8148                    .iter()
8149                    .map(|key| match encoded.get(*key) {
8150                        Some(serde_json::Value::Bool(true)) => '1',
8151                        Some(serde_json::Value::Bool(false)) => '0',
8152                        other => panic!("{key} encoded as {other:?}"),
8153                    })
8154                    .collect();
8155                assert_eq!(
8156                    digits, expected,
8157                    "{backend:?}, sequentialize_threads={sequentialize_threads}"
8158                );
8159            }
8160        }
8161    }
8162
8163    #[test]
8164    fn dbt_backend_config_translates_process_signals_to_host_threads() {
8165        let config = prepare_backend_config(super::DetConfig::default(), Backend::Dbt);
8166        assert!(config.backend.needs_killed_thread_rpc_cancellation);
8167        assert!(!config.backend.tracks_process_children);
8168        assert!(!config.backend.runs_exit_robust_list);
8169        assert!(config.backend.requires_thread_directed_process_signals);
8170        assert!(!config.backend.defers_vfork_child_registration);
8171    }
8172
8173    #[test]
8174    fn backend_write_signal_contract_is_explicit() {
8175        for (backend, supports_interruption) in [
8176            (Backend::Ptrace, true),
8177            (Backend::Dbt, false),
8178            (Backend::Kvm, true),
8179            (Backend::Sabre, false),
8180            (Backend::Liteinst, false),
8181            (Backend::InGuestTrap, false),
8182            (Backend::E9patch, true),
8183        ] {
8184            let config = prepare_backend_config(super::DetConfig::default(), backend);
8185            assert_eq!(
8186                config.backend.supports_parked_write_signal_interruption, supports_interruption,
8187                "unexpected parked-write signal support for {backend:?}"
8188            );
8189        }
8190    }
8191
8192    /// Only ptrace delivers the preemption timer, so only it lets a chaos
8193    /// `sched_yield` hand its turn to a thread that may never make a syscall
8194    /// (https://github.com/rrnewton/hermit/issues/4068).
8195    #[test]
8196    fn backend_timer_delivery_is_explicit() {
8197        for (backend, delivers) in [
8198            (Backend::Ptrace, true),
8199            (Backend::Dbt, false),
8200            (Backend::Kvm, false),
8201            (Backend::Sabre, false),
8202            (Backend::Liteinst, false),
8203            (Backend::InGuestTrap, false),
8204            (Backend::E9patch, true),
8205        ] {
8206            let config = prepare_backend_config(super::DetConfig::default(), backend);
8207            assert_eq!(
8208                config.backend.delivers_preemption_timer_events, delivers,
8209                "unexpected timer delivery for {backend:?}"
8210            );
8211        }
8212    }
8213
8214    /// Only SaBRe and in-guest LiteInst run guest code inside a Tool handler,
8215    /// between two injected calls.
8216    #[test]
8217    fn backend_guest_code_between_injections_is_explicit() {
8218        for (backend, runs) in [
8219            (Backend::Ptrace, false),
8220            (Backend::Dbt, false),
8221            (Backend::Kvm, false),
8222            (Backend::Sabre, true),
8223            (Backend::Liteinst, true),
8224            (Backend::InGuestTrap, true),
8225            (Backend::E9patch, false),
8226        ] {
8227            let config = prepare_backend_config(super::DetConfig::default(), backend);
8228            assert_eq!(
8229                config.backend.runs_guest_code_between_injections, runs,
8230                "unexpected guest code between injections for {backend:?}"
8231            );
8232        }
8233    }
8234
8235    #[test]
8236    fn backend_blocked_wait_signal_contract_is_explicit() {
8237        for (backend, supports_interruption) in [
8238            (Backend::Ptrace, true),
8239            (Backend::Dbt, false),
8240            (Backend::Kvm, false),
8241            (Backend::Sabre, false),
8242            (Backend::Liteinst, false),
8243            (Backend::InGuestTrap, false),
8244            (Backend::E9patch, true),
8245        ] {
8246            let config = prepare_backend_config(super::DetConfig::default(), backend);
8247            assert_eq!(
8248                config.backend.supports_blocked_wait_signal_interruption, supports_interruption,
8249                "unexpected blocked-wait signal support for {backend:?}"
8250            );
8251        }
8252    }
8253
8254    /// A launch may pass the guest a terminal when a standard descriptor is
8255    /// one, when the launcher has a controlling terminal, or when that cannot
8256    /// be read; only a launch with neither is known not to. The device number
8257    /// is read past a command name that holds spaces and parentheses.
8258    #[test]
8259    fn a_launch_may_pass_a_terminal_unless_it_proves_it_has_none() {
8260        assert!(!super::may_pass_a_terminal(false, Some(0)));
8261        assert!(super::may_pass_a_terminal(true, Some(0)));
8262        assert!(super::may_pass_a_terminal(false, Some(34817)));
8263        assert!(super::may_pass_a_terminal(false, None));
8264
8265        let stat = "4242 (a) b (c)) S 1 4242 4242 34817 4242 4194560 0 0 0 0";
8266        assert_eq!(super::parse_controlling_terminal_device(stat), Some(34817));
8267        let stat = "4242 (hermit) S 1 4242 4242 0 -1 4194560 0 0 0 0";
8268        assert_eq!(super::parse_controlling_terminal_device(stat), Some(0));
8269        assert_eq!(
8270            super::parse_controlling_terminal_device("4242 (hermit"),
8271            None
8272        );
8273        assert_eq!(
8274            super::parse_controlling_terminal_device("4242 (hermit) S 1"),
8275            None
8276        );
8277        assert!(super::controlling_terminal_device().is_some());
8278    }
8279
8280    /// Only a backend whose blocked waits decide interruption from the kernel's
8281    /// signal state asks whether the launch may pass the guest a terminal.
8282    #[test]
8283    fn only_gated_backends_record_an_inherited_terminal() {
8284        for backend in [
8285            Backend::Dbt,
8286            Backend::Kvm,
8287            Backend::Sabre,
8288            Backend::Liteinst,
8289            Backend::InGuestTrap,
8290            Backend::E9patch,
8291        ] {
8292            let config = prepare_backend_config(super::DetConfig::default(), backend);
8293            assert!(
8294                !config.guest_may_inherit_a_terminal,
8295                "unexpected terminal record for {backend:?}"
8296            );
8297        }
8298        let config = prepare_backend_config(super::DetConfig::default(), Backend::Ptrace);
8299        assert_eq!(
8300            config.guest_may_inherit_a_terminal,
8301            super::launcher_may_pass_a_terminal()
8302        );
8303    }
8304
8305    #[test]
8306    fn liteinst_public_dispatch_runs_in_guest_detcore() {
8307        if Backend::Liteinst.ensure_available().is_err() {
8308            return;
8309        }
8310
8311        // In-guest LiteInst has no preemption timer and refuses a maximum
8312        // timeslice, so this run disables preemption; preemption is not what
8313        // this test checks.
8314        let config = super::DetConfig {
8315            max_timeslice: None,
8316            ..super::DetConfig::default()
8317        };
8318        let mut command = super::Command::new("/bin/echo");
8319        command.arg("hello");
8320        let output = super::run_with_output_backend(
8321            command,
8322            config.clone(),
8323            false,
8324            &None,
8325            Backend::Liteinst,
8326        )
8327        .expect("run /bin/echo through in-guest LiteInst");
8328        // Include captured output so a failed backend launch reports its diagnostics.
8329        assert_eq!(
8330            output.status,
8331            super::ExitStatus::Exited(0),
8332            "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8333            String::from_utf8_lossy(&output.stderr),
8334            String::from_utf8_lossy(&output.stdout),
8335        );
8336        assert_eq!(output.stdout, b"hello\n");
8337
8338        let status = super::run_with_backend(
8339            super::Command::new("/bin/true"),
8340            config,
8341            false,
8342            &None,
8343            Backend::Liteinst,
8344        )
8345        .expect("run /bin/true through in-guest LiteInst");
8346        assert_eq!(status, super::ExitStatus::Exited(0));
8347    }
8348
8349    #[test]
8350    #[cfg(feature = "dbt")]
8351    fn default_and_available_backends_reflect_host_probes() {
8352        assert_eq!(Backend::default(), Backend::Ptrace);
8353        let available = Backend::available().collect::<Vec<_>>();
8354        assert_eq!(
8355            available.contains(&Backend::Ptrace),
8356            Backend::Ptrace.is_available()
8357        );
8358        assert_eq!(
8359            available.contains(&Backend::Dbt),
8360            dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none()
8361        );
8362        assert_eq!(
8363            available.contains(&Backend::Liteinst),
8364            liteinst_unavailable_reason().is_none()
8365        );
8366        // The same runtime, so available exactly when liteinst is.
8367        assert_eq!(
8368            available.contains(&Backend::InGuestTrap),
8369            available.contains(&Backend::Liteinst)
8370        );
8371        assert_eq!(
8372            available.contains(&Backend::Sabre),
8373            Backend::Sabre.is_available()
8374        );
8375        assert_eq!(
8376            available.contains(&Backend::Kvm),
8377            kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
8378        );
8379        assert_eq!(
8380            available.contains(&Backend::E9patch),
8381            Backend::E9patch.is_available()
8382        );
8383    }
8384
8385    #[test]
8386    #[cfg(feature = "dbt")]
8387    fn dependency_probes_require_usable_paths() {
8388        let temp = tempfile::tempdir().unwrap();
8389        assert!(!is_dynamorio_sdk(temp.path()));
8390        fs::create_dir(temp.path().join("include")).unwrap();
8391        fs::write(temp.path().join("include/dr_api.h"), b"/* marker */").unwrap();
8392        assert!(is_dynamorio_sdk(temp.path()));
8393
8394        let reason = kvm_device_unavailable_reason(temp.path())
8395            .expect("a directory must not pass the read-write KVM device probe");
8396        assert!(reason.contains("read-write"));
8397    }
8398
8399    #[cfg(feature = "sabre")]
8400    fn write_test_executable(path: &std::path::Path) {
8401        fs::create_dir_all(path.parent().unwrap()).unwrap();
8402        fs::write(path, b"test loader").unwrap();
8403        let mut permissions = fs::metadata(path).unwrap().permissions();
8404        permissions.set_mode(0o700);
8405        fs::set_permissions(path, permissions).unwrap();
8406    }
8407
8408    #[test]
8409    #[cfg(feature = "sabre")]
8410    fn sabre_rpc_socket_uses_private_exec_environment() {
8411        assert!(SABRE_RPC_SOCKET_ENV.starts_with("REVERIE_SABRE_"));
8412    }
8413
8414    #[test]
8415    #[cfg(feature = "sabre")]
8416    fn sabre_stages_program_names_that_collide_with_loader_prefix() {
8417        assert!(sabre_program_needs_neutral_name(
8418            PathBuf::from("/usr/bin/ld").as_path()
8419        ));
8420        assert!(sabre_program_needs_neutral_name(
8421            PathBuf::from("/usr/bin/ld.bfd").as_path()
8422        ));
8423        assert!(!sabre_program_needs_neutral_name(
8424            PathBuf::from("/usr/bin/gold").as_path()
8425        ));
8426    }
8427
8428    #[test]
8429    #[cfg(feature = "sabre")]
8430    fn sabre_neutral_name_staging_preserves_program_bytes_and_cleans_up() {
8431        let temp = tempfile::tempdir().unwrap();
8432        let program = temp.path().join("ld.test");
8433        fs::write(&program, b"linker image").unwrap();
8434
8435        let staged = stage_sabre_program_in(&program, temp.path())
8436            .unwrap()
8437            .expect("ld-prefixed program should be staged");
8438        let staged_path = staged.path.clone();
8439        assert_eq!(fs::read(&staged_path).unwrap(), b"linker image");
8440        assert!(
8441            staged_path
8442                .file_name()
8443                .unwrap()
8444                .as_encoded_bytes()
8445                .starts_with(b"hermit-sabre-program-")
8446        );
8447
8448        drop(staged);
8449        assert!(!staged_path.exists());
8450    }
8451
8452    #[tokio::test(start_paused = true)]
8453    #[cfg(feature = "sabre")]
8454    async fn sabre_rpc_disconnect_wait_observes_delayed_release() {
8455        let global = Arc::new(());
8456        let connection = global.clone();
8457        tokio::spawn(async move {
8458            tokio::time::sleep(Duration::from_millis(10)).await;
8459            drop(connection);
8460        });
8461
8462        assert_eq!(
8463            wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(50)).await,
8464            Ok(())
8465        );
8466    }
8467
8468    #[tokio::test(start_paused = true)]
8469    #[cfg(feature = "sabre")]
8470    async fn sabre_rpc_disconnect_wait_reports_stuck_connection() {
8471        let global = Arc::new(());
8472        let _connection = global.clone();
8473
8474        assert_eq!(
8475            wait_for_sabre_rpc_disconnects(&global, Duration::from_millis(10)).await,
8476            Err(1)
8477        );
8478    }
8479
8480    #[tokio::test]
8481    #[cfg(feature = "sabre")]
8482    async fn sabre_rpc_server_intentional_abort_is_clean() {
8483        let server_task = tokio::spawn(std::future::pending::<Result<(), &'static str>>());
8484
8485        assert!(stop_sabre_rpc_server(server_task).await.is_ok());
8486    }
8487
8488    #[tokio::test]
8489    #[cfg(feature = "sabre")]
8490    async fn sabre_rpc_server_failure_is_reported() {
8491        let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
8492        while !server_task.is_finished() {
8493            tokio::task::yield_now().await;
8494        }
8495
8496        let error = stop_sabre_rpc_server(server_task).await.unwrap_err();
8497        assert!(error.to_string().contains("accept failed"));
8498    }
8499
8500    #[tokio::test(start_paused = true)]
8501    #[cfg(feature = "sabre")]
8502    async fn sabre_rpc_shutdown_drains_connections_after_server_failure() {
8503        let global = Arc::new(());
8504        let connection = global.clone();
8505        tokio::spawn(async move {
8506            tokio::time::sleep(Duration::from_millis(10)).await;
8507            drop(connection);
8508        });
8509        let server_task = tokio::spawn(async { Err::<(), _>("accept failed") });
8510        while !server_task.is_finished() {
8511            tokio::task::yield_now().await;
8512        }
8513
8514        let error = shutdown_sabre_rpc(server_task, &global, Duration::from_millis(50))
8515            .await
8516            .unwrap_err();
8517        assert!(error.to_string().contains("accept failed"));
8518        assert_eq!(Arc::strong_count(&global), 1);
8519    }
8520
8521    #[test]
8522    #[cfg(feature = "sabre")]
8523    fn sabre_binary_resolver_finds_cargo_target_build() {
8524        let temp = tempfile::tempdir().unwrap();
8525        let executable = temp.path().join("target/release/hermit");
8526        let loader = temp.path().join("target/sabre/sabre");
8527        write_test_executable(&loader);
8528
8529        assert_eq!(
8530            resolve_sabre_binary_from(None, None, &executable, OsStr::new("")).unwrap(),
8531            loader
8532        );
8533    }
8534
8535    #[test]
8536    #[cfg(feature = "sabre")]
8537    fn sabre_binary_resolver_uses_packaged_loader() {
8538        let temp = tempfile::tempdir().unwrap();
8539        let executable = temp.path().join("target/release/hermit");
8540        let packaged = temp.path().join("install_pkg/rsrcs/sabre");
8541        write_test_executable(&packaged);
8542
8543        assert_eq!(
8544            resolve_sabre_binary_from(None, Some(&packaged), &executable, OsStr::new("")).unwrap(),
8545            packaged
8546        );
8547    }
8548
8549    #[test]
8550    #[cfg(feature = "sabre")]
8551    fn sabre_binary_resolver_prefers_and_validates_override() {
8552        let temp = tempfile::tempdir().unwrap();
8553        let executable = temp.path().join("target/release/hermit");
8554        let discovered = temp.path().join("target/sabre/sabre");
8555        let requested = temp.path().join("requested-sabre");
8556        write_test_executable(&discovered);
8557        write_test_executable(&requested);
8558
8559        assert_eq!(
8560            resolve_sabre_binary_from(
8561                Some(requested.as_os_str()),
8562                Some(&discovered),
8563                &executable,
8564                OsStr::new(""),
8565            )
8566            .unwrap(),
8567            requested
8568        );
8569
8570        let mut permissions = fs::metadata(&requested).unwrap().permissions();
8571        permissions.set_mode(0o600);
8572        fs::set_permissions(&requested, permissions).unwrap();
8573        let error = resolve_sabre_binary_from(
8574            Some(requested.as_os_str()),
8575            Some(&discovered),
8576            &executable,
8577            OsStr::new(""),
8578        )
8579        .unwrap_err();
8580        assert!(error.to_string().contains("is not an executable file"));
8581    }
8582
8583    #[test]
8584    #[cfg(feature = "dbt")]
8585    fn optional_backends_report_accurate_availability() {
8586        match Backend::Dbt.ensure_available() {
8587            Ok(()) => assert!(
8588                dynamorio_sdk_available() && dbt_runtime_unavailable_reason().is_none(),
8589                "DBT reported available without its SDK and runtime"
8590            ),
8591            Err(dbt_error) => {
8592                let message = dbt_error.to_string();
8593                assert!(
8594                    message.contains("DynamoRIO runtime")
8595                        || message.contains("Detcore DBT runtime"),
8596                    "unexpected DBT availability error: {message}"
8597                );
8598            }
8599        }
8600        assert_eq!(
8601            Backend::Liteinst.ensure_available().is_ok(),
8602            liteinst_unavailable_reason().is_none()
8603        );
8604        assert_eq!(
8605            Backend::InGuestTrap.ensure_available().is_ok(),
8606            liteinst_unavailable_reason().is_none()
8607        );
8608
8609        match Backend::Kvm.ensure_available() {
8610            Ok(()) => assert!(
8611                kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_none(),
8612                "KVM reported available without a usable /dev/kvm",
8613            ),
8614            Err(kvm_error) => {
8615                let message = kvm_error.to_string();
8616                assert!(
8617                    message.contains("/dev/kvm"),
8618                    "unexpected KVM availability error: {message}",
8619                );
8620                assert!(!message.contains("requires root privileges"));
8621            }
8622        }
8623    }
8624
8625    #[test]
8626    fn public_backend_dispatch_rejects_unprepared_e9patch() {
8627        let error = ensure_backend_dispatch(Backend::E9patch).unwrap_err();
8628        assert!(
8629            error.to_string().contains("requires CLI preprocessing"),
8630            "unexpected error: {error}"
8631        );
8632    }
8633
8634    #[test]
8635    #[cfg(feature = "dbt")]
8636    fn dbt_retries_only_the_pre_guest_bootstrap_failure() {
8637        use std::os::unix::process::ExitStatusExt as _;
8638
8639        let failure = std::process::ExitStatus::from_raw(
8640            reverie_dbt::CLIENT_THREAD_START_FAILURE_EXIT_CODE << 8,
8641        );
8642        assert!(super::dbt_client_thread_start_failed(&failure));
8643        assert!(!super::dbt_client_thread_start_failed(
8644            &std::process::ExitStatus::from_raw(1 << 8)
8645        ));
8646    }
8647
8648    #[test]
8649    #[cfg(feature = "dbt")]
8650    fn dbt_public_dispatch_requires_sequentialized_threads() {
8651        let command = super::Command::new("/bin/true");
8652        let config = super::DetConfig {
8653            sequentialize_threads: false,
8654            ..Default::default()
8655        };
8656
8657        let error = super::run_with_output_backend(command, config, false, &None, Backend::Dbt)
8658            .expect_err("DBT must reject non-sequentialized execution");
8659        assert!(
8660            error
8661                .to_string()
8662                .contains("dbt backend requires sequentialized threads"),
8663            "unexpected error: {error}"
8664        );
8665    }
8666
8667    #[test]
8668    #[cfg(feature = "dbt")]
8669    fn dbt_public_dispatch_runs_echo_through_detcore() {
8670        use clap::Parser;
8671
8672        if Backend::Dbt.ensure_available().is_err() {
8673            return;
8674        }
8675
8676        // Isolate the controller's fd 2 in a subprocess, without redirecting a
8677        // descriptor shared by other tests in this process.
8678        const CHILD: &str = "HERMIT_TEST_DBT_LIBRARY_DIAGNOSTICS_CHILD";
8679        if std::env::var_os(CHILD).is_none() {
8680            let output = std::process::Command::new(std::env::current_exe().unwrap())
8681                .args([
8682                    "--exact",
8683                    "tests::dbt_public_dispatch_runs_echo_through_detcore",
8684                    "--nocapture",
8685                ])
8686                .env(CHILD, "1")
8687                .output()
8688                .expect("run isolated DBT library output checks");
8689            let diagnostics = String::from_utf8_lossy(&output.stderr);
8690            assert!(output.status.success(), "{output:?}");
8691            assert!(
8692                diagnostics
8693                    .lines()
8694                    .filter(|line| line.starts_with("reverie-dbt: tool=Detcore "))
8695                    .count()
8696                    >= 2,
8697                "DBT native summaries did not prove both Detcore dispatches: {diagnostics}"
8698            );
8699            assert!(!diagnostics.contains("guest-stderr"), "{diagnostics}");
8700            return;
8701        }
8702
8703        let mut command = super::Command::new("/bin/echo");
8704        command.arg("hello");
8705        let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8706        config.sequentialize_threads = true;
8707        config.validate();
8708        let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
8709            .expect("run /bin/echo through DbtGuest<Detcore>");
8710
8711        // Include captured output so a failed backend launch reports its diagnostics.
8712        assert_eq!(
8713            output.status,
8714            super::ExitStatus::Exited(0),
8715            "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8716            String::from_utf8_lossy(&output.stderr),
8717            String::from_utf8_lossy(&output.stdout),
8718        );
8719        assert_eq!(output.stdout, b"hello\n");
8720        assert_eq!(output.stderr, b"");
8721
8722        let mut command = super::Command::new("/bin/sh");
8723        command.args(["-c", "printf 'guest-stderr\\n' >&2"]);
8724        let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8725        config.sequentialize_threads = true;
8726        config.validate();
8727        let output = super::run_with_output_backend(command, config, true, &None, Backend::Dbt)
8728            .expect("capture nonempty guest stderr through DbtGuest<Detcore>");
8729        assert_eq!(output.status, super::ExitStatus::Exited(0), "{output:?}");
8730        assert_eq!(output.stdout, b"");
8731        assert_eq!(output.stderr, b"guest-stderr\n");
8732    }
8733
8734    #[test]
8735    #[cfg(feature = "dbt")]
8736    fn dbt_public_status_dispatch_runs_true_through_detcore() {
8737        use clap::Parser;
8738
8739        if Backend::Dbt.ensure_available().is_err() {
8740            return;
8741        }
8742
8743        let command = super::Command::new("/bin/true");
8744        let mut config = super::DetConfig::parse_from(["hermit-dbt-test"]);
8745        config.sequentialize_threads = true;
8746        config.validate();
8747        let status = super::run_with_backend(command, config, true, &None, Backend::Dbt)
8748            .expect("run /bin/true through DbtGuest<Detcore>");
8749
8750        assert_eq!(status, super::ExitStatus::Exited(0));
8751    }
8752
8753    #[test]
8754    fn kvm_runs_dynamic_echo_through_detcore() {
8755        use clap::Parser;
8756
8757        if kvm_device_unavailable_reason(std::path::Path::new("/dev/kvm")).is_some() {
8758            return;
8759        }
8760
8761        let mut command = super::Command::new("/bin/echo");
8762        command.arg("hello");
8763        let mut config = super::DetConfig::parse_from(["hermit-kvm-test"]);
8764        config.validate();
8765        let output = super::run_with_output_backend(command, config, false, &None, Backend::Kvm)
8766            .expect("run dynamic /bin/echo through KvmGuest<Detcore>");
8767
8768        // Include captured output so a failed backend launch reports its diagnostics.
8769        assert_eq!(
8770            output.status,
8771            super::ExitStatus::Exited(0),
8772            "guest did not exit 0.\n--- guest stderr ---\n{}\n--- guest stdout ---\n{}",
8773            String::from_utf8_lossy(&output.stderr),
8774            String::from_utf8_lossy(&output.stdout),
8775        );
8776        assert_eq!(output.stdout, b"hello\n");
8777        assert!(output.stderr.is_empty());
8778    }
8779
8780    // Keep the low-level vmcall transport covered independently from the ELF
8781    // process personality. Requires /dev/kvm; skips cleanly otherwise.
8782    #[test]
8783    fn detcore_drives_kvm_guest_for_synthetic_syscall() {
8784        use clap::Parser;
8785
8786        const MEMORY_SIZE: usize = 0x10_000;
8787        const ENTRY_POINT: u64 = 0x1000;
8788        const FRAME_ADDRESS: u64 = 0x2000;
8789
8790        let mut backend = match reverie_kvm::KvmBackend::new(MEMORY_SIZE) {
8791            Ok(backend) => backend,
8792            Err(error) => {
8793                eprintln!("skipping KVM Detcore experiment: cannot init VM: {error}");
8794                return;
8795            }
8796        };
8797
8798        // A guest that issues one `getpid` through the vmcall transport, then HLTs.
8799        backend
8800            .install_syscall(
8801                ENTRY_POINT,
8802                FRAME_ADDRESS,
8803                reverie_kvm::SyscallRequest::new(libc::SYS_getpid as u64, [0; 6]),
8804            )
8805            .expect("install synthetic getpid guest");
8806
8807        // Minimal deterministic Detcore config with RCB preemption disabled.
8808        let mut config =
8809            super::DetConfig::parse_from(["hermit-kvm-test", "--max-timeslice=disabled"]);
8810        config.validate();
8811
8812        let runtime = tokio::runtime::Builder::new_current_thread()
8813            .enable_all()
8814            .build()
8815            .expect("build tokio runtime");
8816
8817        let outcome = runtime.block_on(async {
8818            backend
8819                .run_with_tool::<super::Detcore, _>(
8820                    config,
8821                    // Executor: forward anything Detcore injects to the host.
8822                    |request: &reverie_kvm::SyscallRequest, _memory: &reverie_kvm::GuestMemory| {
8823                        // SAFETY: forwarding a register-only syscall (getpid) to the
8824                        // host; no guest pointers are dereferenced by the kernel.
8825                        unsafe {
8826                            libc::syscall(
8827                                request.number() as libc::c_long,
8828                                request.args()[0],
8829                                request.args()[1],
8830                                request.args()[2],
8831                                request.args()[3],
8832                                request.args()[4],
8833                                request.args()[5],
8834                            ) as i64
8835                        }
8836                    },
8837                )
8838                .await
8839        });
8840
8841        // The point of the experiment is to observe whether Detcore can be driven
8842        // to completion over KvmGuest at all; assert it did not error.
8843        outcome.expect("Detcore drove the synthetic KVM guest to completion");
8844    }
8845
8846    // Minimal fake ELF payload: the loader only needs the image to NOT start
8847    // with `#!`, and a real ELF magic makes the intent obvious.
8848    const FAKE_ELF: &[u8] = b"\x7fELF\x02\x01\x01\x00 fake elf body";
8849
8850    fn shebang_tmpdir(tag: &str) -> PathBuf {
8851        let dir = std::env::temp_dir().join(format!(
8852            "hermit-shebang-test-{}-{}",
8853            std::process::id(),
8854            tag
8855        ));
8856        let _ = fs::remove_dir_all(&dir);
8857        fs::create_dir_all(&dir).unwrap();
8858        dir
8859    }
8860
8861    #[test]
8862    fn resolve_shebang_plain_elf_is_unchanged() {
8863        let dir = shebang_tmpdir("plain");
8864        let prog = dir.join("prog");
8865        fs::write(&prog, FAKE_ELF).unwrap();
8866
8867        let argv = vec!["prog".to_owned(), "-a".to_owned()];
8868        let (path, out_argv, image) = resolve_kvm_shebang(&prog, argv).unwrap();
8869        assert_eq!(path, prog);
8870        assert_eq!(out_argv, vec!["prog".to_owned(), "-a".to_owned()]);
8871        assert_eq!(image, FAKE_ELF);
8872        fs::remove_dir_all(&dir).unwrap();
8873    }
8874
8875    #[test]
8876    fn resolve_shebang_single_level_kernel_order() {
8877        let dir = shebang_tmpdir("single");
8878        let interp = dir.join("fakebash");
8879        fs::write(&interp, FAKE_ELF).unwrap();
8880        let script = dir.join("script");
8881        // Interpreter with a single optional argument.
8882        fs::write(&script, format!("#!{} -x\necho hi\n", interp.display())).unwrap();
8883
8884        let argv = vec!["script".to_owned(), "arg1".to_owned()];
8885        let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
8886        assert_eq!(path, interp);
8887        // Kernel order: [interp, optarg, script_path, original args after argv[0]].
8888        assert_eq!(
8889            out_argv,
8890            vec![
8891                interp.to_string_lossy().into_owned(),
8892                "-x".to_owned(),
8893                script.to_string_lossy().into_owned(),
8894                "arg1".to_owned(),
8895            ]
8896        );
8897        assert_eq!(image, FAKE_ELF);
8898        fs::remove_dir_all(&dir).unwrap();
8899    }
8900
8901    #[test]
8902    fn resolve_shebang_nested_accumulates_like_binfmt_script() {
8903        let dir = shebang_tmpdir("nested");
8904        let interp = dir.join("fakebash");
8905        fs::write(&interp, FAKE_ELF).unwrap();
8906        let mid = dir.join("mid"); // a #!-interpreter that is itself a script
8907        fs::write(&mid, format!("#!{}\n", interp.display())).unwrap();
8908        let script = dir.join("script");
8909        fs::write(&script, format!("#!{} -e\n", mid.display())).unwrap();
8910
8911        let argv = vec!["script".to_owned(), "arg1".to_owned()];
8912        let (path, out_argv, image) = resolve_kvm_shebang(&script, argv).unwrap();
8913        assert_eq!(path, interp);
8914        // Level 1: [mid, -e, script, arg1]; level 2 prepends [interp, mid].
8915        assert_eq!(
8916            out_argv,
8917            vec![
8918                interp.to_string_lossy().into_owned(),
8919                mid.to_string_lossy().into_owned(),
8920                "-e".to_owned(),
8921                script.to_string_lossy().into_owned(),
8922                "arg1".to_owned(),
8923            ]
8924        );
8925        assert_eq!(image, FAKE_ELF);
8926        fs::remove_dir_all(&dir).unwrap();
8927    }
8928
8929    #[test]
8930    fn resolve_shebang_rejects_infinite_recursion() {
8931        let dir = shebang_tmpdir("loop");
8932        let a = dir.join("a");
8933        let b = dir.join("b");
8934        fs::write(&a, format!("#!{}\n", b.display())).unwrap();
8935        fs::write(&b, format!("#!{}\n", a.display())).unwrap();
8936
8937        let argv = vec!["a".to_owned()];
8938        assert!(resolve_kvm_shebang(&a, argv).is_err());
8939        fs::remove_dir_all(&dir).unwrap();
8940    }
8941
8942    /// The build scripts' pin reader, bracketed against the inputs that
8943    /// first-match-wins got wrong. Included rather than imported because the
8944    /// reader is build-script code with no library home.
8945    mod reverie_pin_reader {
8946        include!("../reverie_pin.rs");
8947
8948        const A: &str = "1111111111111111111111111111111111111111";
8949        const B: &str = "2222222222222222222222222222222222222222";
8950
8951        fn dep(rev: &str) -> String {
8952            format!(
8953                "reverie = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"{rev}\" }}\n"
8954            )
8955        }
8956
8957        #[test]
8958        fn a_single_revision_is_read() {
8959            assert_eq!(parse_reverie_pin(&dep(A)).as_deref(), Some(A));
8960        }
8961
8962        #[test]
8963        fn agreeing_revisions_are_read_once() {
8964            let text = format!("{}{}", dep(A), dep(A));
8965            assert_eq!(parse_reverie_pin(&text).as_deref(), Some(A));
8966        }
8967
8968        /// A manifest halfway through a bump names two revisions. First-match-wins
8969        /// silently returned the first; the canonical rule refuses to resolve it.
8970        #[test]
8971        fn disagreeing_revisions_are_refused() {
8972            let text = format!("{}{}", dep(A), dep(B));
8973            assert_eq!(parse_reverie_pin(&text), None);
8974        }
8975
8976        /// The reported reproduction: ONE commented line above the live pin made
8977        /// the binary embed the comment's revision, so a correctly staged runtime
8978        /// would be refused by a guard naming a revision that was never the pin.
8979        #[test]
8980        fn a_commented_out_dependency_is_not_the_pin() {
8981            let text = format!("# {}{}", dep(B), dep(A));
8982            assert_eq!(
8983                parse_reverie_pin(&text).as_deref(),
8984                Some(A),
8985                "a commented-out revision must not win"
8986            );
8987        }
8988
8989        #[test]
8990        fn a_manifest_naming_no_revision_yields_none() {
8991            assert_eq!(parse_reverie_pin("[dependencies]\nlibc = \"0.2\"\n"), None);
8992        }
8993
8994        /// An unparseable Reverie line could be hiding a disagreement, so it makes
8995        /// the manifest ambiguous rather than being skipped as absent.
8996        #[test]
8997        fn an_unparseable_revision_is_ambiguous() {
8998            let text = format!(
8999                "{}reverie-x = {{ git = \"https://github.com/rrnewton/reverie.git\", rev = \"beef\" }}\n",
9000                dep(A)
9001            );
9002            assert_eq!(parse_reverie_pin(&text), None);
9003        }
9004    }
9005
9006    /// SaBRe's guest plugin has no subscriber, so it forwards DETLOG records by
9007    /// the policy the CLI hands it. For each filter the CLI builds, that policy
9008    /// must answer every emitting module as the CLI's own subscriber does,
9009    /// which is what each in-process `detlog!` callsite asks under ptrace.
9010    /// `warn,detcore::random=info` once yielded no forwarding at all, because
9011    /// only the generic `detcore` target was asked, so SaBRe dropped the
9012    /// AT_RANDOM and early getrandom records ptrace prints.
9013    #[cfg(feature = "sabre")]
9014    #[test]
9015    fn sabre_detlog_forwarding_answers_each_target_as_the_cli_filter_does() {
9016        use detcore::detlog::ForwardPolicy;
9017        use detcore::detlog::info_enabled_for_target;
9018        use tracing::level_filters::LevelFilter;
9019        use tracing_subscriber::layer::SubscriberExt;
9020
9021        use crate::liteinst_bootstrap::EffectiveFilter;
9022
9023        let targets = [
9024            "",
9025            "detcore",
9026            "detcore::random",
9027            "detcore::randomness",
9028            "detcore::tool_local",
9029            "detcore::scheduler",
9030            "detcore::scheduler::runqueue",
9031            "detcore::syscalls::files",
9032            "hermit",
9033            "warn",
9034        ];
9035        let policy_under = |raw: &str, level: LevelFilter| {
9036            let subscriber = tracing_subscriber::registry()
9037                .with(EffectiveFilter::from_directives_lossy(raw, level).into_filter());
9038            tracing::subscriber::with_default(subscriber, || {
9039                let policy = ForwardPolicy::from_current_subscriber(raw);
9040                let subscriber_says: Vec<bool> = targets
9041                    .iter()
9042                    .map(|target| info_enabled_for_target(target))
9043                    .collect();
9044                (policy, subscriber_says)
9045            })
9046        };
9047        for (raw, level) in [
9048            ("warn,detcore::random=info", LevelFilter::WARN),
9049            ("detcore::random=info", LevelFilter::WARN),
9050            ("detcore::random=warn", LevelFilter::INFO),
9051            (
9052                "warn,detcore=info,detcore::scheduler=off",
9053                LevelFilter::WARN,
9054            ),
9055            (
9056                "warn,detcore[work]=info,detcore::random=info",
9057                LevelFilter::WARN,
9058            ),
9059            ("", LevelFilter::INFO),
9060            ("", LevelFilter::WARN),
9061        ] {
9062            let (policy, subscriber_says) = policy_under(raw, level);
9063            for (target, enabled) in targets.iter().zip(subscriber_says) {
9064                assert_eq!(
9065                    policy.forwards(target),
9066                    enabled,
9067                    "RUST_LOG={raw:?} --log={level}: policy {policy:?} disagrees on {target:?}"
9068                );
9069            }
9070        }
9071
9072        let (scoped, subscriber_says) =
9073            policy_under("warn,detcore::random=info", LevelFilter::WARN);
9074        assert!(!subscriber_says[1], "the generic detcore target is off");
9075        assert!(scoped.forwards_any());
9076        assert!(scoped.forwards("detcore::random"));
9077        assert!(!scoped.forwards("detcore::tool_local"));
9078        assert_eq!(policy_under("", LevelFilter::INFO).0, ForwardPolicy::all());
9079        assert!(!policy_under("", LevelFilter::WARN).0.forwards_any());
9080    }
9081
9082    /// In-guest LiteInst gets the per-target policy it is given next to the
9083    /// forwarding descriptor, and this build's fingerprint, in the launch
9084    /// record, with none of Hermit's variables left on the command; a policy
9085    /// that forwards nothing requests no forwarding.
9086    #[cfg(feature = "liteinst")]
9087    #[test]
9088    fn liteinst_launch_hands_the_guest_its_per_target_policy() {
9089        use std::os::fd::AsRawFd;
9090
9091        use detcore::detlog::ForwardPolicy;
9092        use detcore::in_guest_launch::InGuestLaunch;
9093        use reverie::process::Command;
9094
9095        use super::LITEINST_DETLOG_FORWARD_ENV;
9096        use super::LITEINST_DETLOG_FORWARD_POLICY_ENV;
9097        use super::forward_in_guest_detlogs_to;
9098        use super::in_guest_liteinst_launch;
9099
9100        let (sink, _peer) = std::os::unix::net::UnixDatagram::pair().unwrap();
9101        forward_in_guest_detlogs_to(sink.into());
9102        let removed = |command: &Command| {
9103            [
9104                LITEINST_DETLOG_FORWARD_ENV,
9105                LITEINST_DETLOG_FORWARD_POLICY_ENV,
9106                detcore::LITEINST_CONFIG_FINGERPRINT_ENV,
9107            ]
9108            .into_iter()
9109            .all(|key| {
9110                command
9111                    .get_envs()
9112                    .any(|(name, value)| name == std::ffi::OsStr::new(key) && value.is_none())
9113            })
9114        };
9115
9116        let scoped = ForwardPolicy::decode("0,detcore::random=1").unwrap();
9117        let mut command = Command::new("/bin/true");
9118        let (launch, duplicate) = in_guest_liteinst_launch(&mut command, &scoped).unwrap();
9119        let duplicate = duplicate.expect("a policy that forwards a target requests forwarding");
9120        assert!(removed(&command));
9121        let launch = InGuestLaunch::decode(&launch.encode()).unwrap();
9122        let passed = launch.forward_request.expect("the descriptor is passed");
9123        assert_eq!(
9124            detcore::detlog::tool_output_env_target(&passed),
9125            Some(duplicate.as_raw_fd()),
9126            "{passed}"
9127        );
9128        let sent =
9129            ForwardPolicy::decode(&launch.forward_policy.expect("the policy goes too")).unwrap();
9130        assert_eq!(sent, scoped);
9131        assert!(sent.forwards("detcore::random"));
9132        assert!(!sent.forwards("detcore::tool_local"));
9133        assert_eq!(
9134            launch.coordinator_fingerprint,
9135            Some(detcore::config_wire_fingerprint())
9136        );
9137
9138        let nothing = ForwardPolicy::decode("0").unwrap();
9139        let mut command = Command::new("/bin/true");
9140        command
9141            .env(LITEINST_DETLOG_FORWARD_ENV, "9")
9142            .env(LITEINST_DETLOG_FORWARD_POLICY_ENV, "1")
9143            .env(detcore::LITEINST_CONFIG_FINGERPRINT_ENV, "0000000000000000");
9144        let (launch, duplicate) = in_guest_liteinst_launch(&mut command, &nothing).unwrap();
9145        assert!(duplicate.is_none());
9146        assert!(removed(&command));
9147        assert_eq!(launch.forward_request, None);
9148        assert_eq!(launch.forward_policy, None);
9149    }
9150
9151    /// The forwarding policy answers as a real in-process `detlog!` record
9152    /// behaves under the CLI's filter: a record is logged only when both its
9153    /// `tracing::enabled!` hint and its event pass, and a directive with a
9154    /// field filter applies to the hint whatever its fields but to the event
9155    /// only when the event has that field. `info,<module>[{unused}]=warn`
9156    /// suppresses the record; the policy once forwarded it, because it probed
9157    /// only the event.
9158    #[test]
9159    fn detlog_forward_policy_matches_real_detlog_emission_under_field_filters() {
9160        use std::sync::Arc;
9161        use std::sync::atomic::AtomicUsize;
9162        use std::sync::atomic::Ordering;
9163
9164        use detcore::detlog::ForwardPolicy;
9165        use tracing::level_filters::LevelFilter;
9166        use tracing_subscriber::layer::SubscriberExt;
9167
9168        use crate::liteinst_bootstrap::EffectiveFilter;
9169
9170        struct Count(Arc<AtomicUsize>);
9171        impl<S: tracing::Subscriber> tracing_subscriber::Layer<S> for Count {
9172            fn on_event(
9173                &self,
9174                _event: &tracing::Event<'_>,
9175                _context: tracing_subscriber::layer::Context<'_, S>,
9176            ) {
9177                self.0.fetch_add(1, Ordering::Relaxed);
9178            }
9179        }
9180
9181        let module = module_path!();
9182        for (raw, level) in [
9183            (format!("info,{module}[{{unused}}]=warn"), LevelFilter::INFO),
9184            (
9185                format!("warn,{module}[{{unused}}]=trace"),
9186                LevelFilter::WARN,
9187            ),
9188            (
9189                format!("info,{module}[{{message}}]=warn"),
9190                LevelFilter::INFO,
9191            ),
9192            (format!("info,{module}=warn"), LevelFilter::INFO),
9193            (format!("warn,{module}=info"), LevelFilter::WARN),
9194            ("info".to_owned(), LevelFilter::INFO),
9195            ("warn".to_owned(), LevelFilter::WARN),
9196        ] {
9197            let emitted = Arc::new(AtomicUsize::new(0));
9198            let subscriber = tracing_subscriber::registry()
9199                .with(EffectiveFilter::from_directives_lossy(&raw, level).into_filter())
9200                .with(Count(emitted.clone()));
9201            let forwards = tracing::subscriber::with_default(subscriber, || {
9202                detcore::detlog!("probe record");
9203                ForwardPolicy::from_current_subscriber(&raw).forwards(module)
9204            });
9205            assert_eq!(
9206                forwards,
9207                emitted.load(Ordering::Relaxed) == 1,
9208                "RUST_LOG={raw:?} --log={level}: the policy and a real detlog! disagree"
9209            );
9210        }
9211    }
9212}