H1: child processes die with Lutra (crates/proc)

New layer-0 crate lutra-proc: spawn(Command) puts the child into a
kill-on-close group. Windows: one job object per child with
JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE (windows-sys), nested jobs work.
Unix: a new process group plus a /bin/sh watchdog that kills the group
when Lutra's pipe closes (drop, kill, quit or SIGKILL of Lutra).
Child::kill and Drop take the whole group.

Phpactor (supervision spawn) and the php -v probe in lutra-lsp start
through it. Tests kill a parent hard and check that its child is gone
(with and without the parent in a group), plus kill and drop of a tree.
Docs: architecture "Child processes", G6 note.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 12:59:57 +01:00
parent e5891ddeb4
commit 90d03284f2
13 changed files with 555 additions and 14 deletions

8
Cargo.lock generated
View file

@ -2659,6 +2659,7 @@ dependencies = [
name = "lutra-lsp" name = "lutra-lsp"
version = "0.0.0" version = "0.0.0"
dependencies = [ dependencies = [
"lutra-proc",
"lutra-text", "lutra-text",
"lutra-vfs", "lutra-vfs",
"proptest", "proptest",
@ -2683,6 +2684,13 @@ dependencies = [
"tempfile", "tempfile",
] ]
[[package]]
name = "lutra-proc"
version = "0.0.0"
dependencies = [
"windows-sys 0.61.2",
]
[[package]] [[package]]
name = "lutra-search" name = "lutra-search"
version = "0.0.0" version = "0.0.0"

View file

@ -13,6 +13,7 @@ publish = false
[workspace.dependencies] [workspace.dependencies]
lutra-text = { path = "crates/text" } lutra-text = { path = "crates/text" }
lutra-proc = { path = "crates/proc" }
lutra-syntax = { path = "crates/syntax" } lutra-syntax = { path = "crates/syntax" }
lutra-vfs = { path = "crates/vfs" } lutra-vfs = { path = "crates/vfs" }
lutra-index = { path = "crates/index" } lutra-index = { path = "crates/index" }

View file

@ -18,6 +18,7 @@ test = false
doc = false doc = false
[dependencies] [dependencies]
lutra-proc.workspace = true
lutra-text.workspace = true lutra-text.workspace = true
lutra-vfs.workspace = true lutra-vfs.workspace = true
ring = "0.17.14" ring = "0.17.14"

View file

@ -20,13 +20,14 @@ use std::ffi::{OsStr, OsString};
use std::io::{BufReader, Write}; use std::io::{BufReader, Write};
use std::panic::{AssertUnwindSafe, catch_unwind}; use std::panic::{AssertUnwindSafe, catch_unwind};
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use std::process::{Child, ChildStdin, Command, Stdio}; use std::process::{ChildStdin, Command, Stdio};
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::mpsc::{self, Receiver, Sender, SyncSender, TrySendError}; use std::sync::mpsc::{self, Receiver, Sender, SyncSender, TrySendError};
use std::sync::{Arc, Mutex, MutexGuard, Weak}; use std::sync::{Arc, Mutex, MutexGuard, Weak};
use std::thread::{self, JoinHandle}; use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant}; use std::time::{Duration, Instant};
use lutra_proc::Child;
use lutra_text::{Buffer, Edit, Position}; use lutra_text::{Buffer, Edit, Position};
use serde_json::{Value, json}; use serde_json::{Value, json};
@ -470,7 +471,9 @@ impl Shared {
self.set_status(&mut state, Status::Ready); self.set_status(&mut state, Status::Ready);
} }
/// Starts the server process with piped stdio and no console window. /// Starts the server process with piped stdio and no console window,
/// in a [`lutra_proc`] group, so it and everything it starts die with
/// Lutra even when Lutra is killed.
/// ///
/// # Errors /// # Errors
/// [`LspError::Spawn`] when the executable cannot be started. /// [`LspError::Spawn`] when the executable cannot be started.
@ -490,7 +493,7 @@ impl Shared {
use std::os::windows::process::CommandExt; use std::os::windows::process::CommandExt;
command.creation_flags(CREATE_NO_WINDOW); command.creation_flags(CREATE_NO_WINDOW);
} }
command.spawn().map_err(|error| LspError::Spawn { lutra_proc::spawn(command).map_err(|error| LspError::Spawn {
command: self.launch.command.to_string_lossy().into_owned(), command: self.launch.command.to_string_lossy().into_owned(),
detail: error.to_string(), detail: error.to_string(),
}) })
@ -711,11 +714,11 @@ enum Exit {
Crashed(String), Crashed(String),
} }
/// Kills and reaps a process. Errors are ignored on purpose: the process /// Kills and reaps a process and everything in its group. Errors are
/// may have exited already, and there is nothing else to do about it. /// ignored on purpose: the process may have exited already, and there is
/// nothing else to do about it.
fn kill(child: &mut Child) { fn kill(child: &mut Child) {
let _ = child.kill(); let _ = child.kill_and_wait();
let _ = child.wait();
} }
/// Calls a reply outside any lock. A panicking callback is caught so it /// Calls a reply outside any lock. A panicking callback is caught so it

View file

@ -188,7 +188,7 @@ pub fn run_version(path: &Path, timeout: Duration) -> Result<Vec<u8>, PhpError>
.stdout(Stdio::piped()) .stdout(Stdio::piped())
.stderr(Stdio::null()); .stderr(Stdio::null());
hide_window(&mut command); hide_window(&mut command);
let mut child = command.spawn().map_err(|e| failed(e.to_string()))?; let mut child = lutra_proc::spawn(command).map_err(|e| failed(e.to_string()))?;
let stdout = child let stdout = child
.stdout .stdout
.take() .take()
@ -208,8 +208,7 @@ pub fn run_version(path: &Path, timeout: Duration) -> Result<Vec<u8>, PhpError>
match child.try_wait() { match child.try_wait() {
Ok(Some(status)) => break status, Ok(Some(status)) => break status,
Ok(None) if Instant::now() >= deadline => { Ok(None) if Instant::now() >= deadline => {
let _ = child.kill(); let _ = child.kill_and_wait();
let _ = child.wait();
return Err(failed(format!( return Err(failed(format!(
"php -v did not finish within {} s", "php -v did not finish within {} s",
timeout.as_secs() timeout.as_secs()

29
crates/proc/Cargo.toml Normal file
View file

@ -0,0 +1,29 @@
[package]
name = "lutra-proc"
description = "Child processes that die with Lutra: job objects on Windows, process groups on Unix"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
[package.metadata.lutra]
layer = 0
[[bin]]
name = "lutra-proc-helper"
path = "src/bin/lutra-proc-helper.rs"
test = false
doc = false
[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61.2", features = [
"Win32_Foundation",
"Win32_Security",
"Win32_System_JobObjects",
"Win32_System_Threading",
] }
[lints]
workspace = true

View file

@ -0,0 +1,77 @@
//! A process tree builder for the `lutra-proc` tests.
//!
//! Not shipped: the integration tests start it through
//! `CARGO_BIN_EXE_lutra-proc-helper`. Roles, by the first argument:
//!
//! - `tree-plain`: starts a sleeping grandchild with a plain
//! [`std::process::Command`], `tree-proc`: starts it through
//! [`lutra_proc::spawn`]. The grandchild is a system program (`ping` on
//! Windows, `sleep` elsewhere) rather than this helper, because virus
//! scanners delay an unsigned program that starts copies of itself by
//! tens of seconds. It gets this process's standard output as its
//! standard error, so it holds the pipe without writing to it. Then this
//! process prints `ready` and sleeps. A test reading that output sees
//! end of file only once the grandchild is gone too, which is how it
//! checks that no process was left behind.
//!
//! Any other argument exits with code 2.
use std::io::Write;
use std::process::{Command, ExitCode, Stdio};
use std::thread;
use std::time::Duration;
/// How long the helper and its grandchild sleep.
const SLEEP: Duration = Duration::from_secs(120);
/// Runs the role named by the first argument.
fn main() -> ExitCode {
let role = std::env::args().nth(1).unwrap_or_default();
match role.as_str() {
"tree-plain" | "tree-proc" => tree(role == "tree-proc"),
_ => ExitCode::from(2),
}
}
/// Starts the grandchild (through `lutra_proc` when `guarded`), prints
/// `ready` and sleeps.
fn tree(guarded: bool) -> ExitCode {
let mut command = grandchild();
command
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::from(std::io::stdout()));
let _guarded;
let _plain;
if guarded {
let Ok(child) = lutra_proc::spawn(command) else {
return ExitCode::from(4);
};
_guarded = child;
} else {
let Ok(child) = command.spawn() else {
return ExitCode::from(4);
};
_plain = child;
}
let mut out = std::io::stdout();
if writeln!(out, "ready").and_then(|()| out.flush()).is_err() {
return ExitCode::from(5);
}
thread::sleep(SLEEP);
ExitCode::SUCCESS
}
/// A system program that sleeps for [`SLEEP`] without output.
fn grandchild() -> Command {
let seconds = SLEEP.as_secs();
if cfg!(windows) {
let mut command = Command::new("ping");
command.args(["-n", &(seconds + 1).to_string(), "127.0.0.1"]);
command
} else {
let mut command = Command::new("sleep");
command.arg(seconds.to_string());
command
}
}

161
crates/proc/src/lib.rs Normal file
View file

@ -0,0 +1,161 @@
//! Child processes that die with Lutra (layer L0).
//!
//! [`spawn`] starts a [`std::process::Command`] inside a group that the
//! operating system tears down when Lutra's process ends, even when Lutra
//! is killed hard, and returns a [`Child`] whose [`Child::kill`] and
//! [`Drop`] take the whole group (the child and everything it started).
//! Phpactor uses it now; git, `php -l` and other tools use it next.
//!
//! - **Windows:** every child gets its own job object with
//! `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`. Lutra holds the only handle, so
//! the job closes, and kills its processes, when the [`Child`] is dropped
//! or when Lutra's process ends in any way (the kernel closes its
//! handles). Jobs nest (Windows 8 and later), so this works when Lutra
//! itself runs inside a job (a terminal, `cargo`, a CI runner).
//! Processes the child starts are in the job too.
//! - **Unix:** the child leads a new process group. A watchdog
//! (`/bin/sh`, in its own process group) blocks on a pipe whose write end
//! only Lutra holds; when the pipe closes, because the [`Child`] is
//! dropped or killed, because Lutra quits, or because Lutra is killed
//! with `SIGKILL`, it sends `SIGKILL` to the child's group. What a
//! `SIGKILL` of Lutra can still leave behind: processes that left the
//! group themselves (`setsid`, `setpgid`, i.e. daemons), and the child if
//! Lutra dies in the microseconds between starting it and starting its
//! watchdog. If the watchdog itself is killed, the group is only killed
//! by an explicit [`Child::kill`] or drop, which then signal the direct
//! child only.
//!
//! A child starts running before it is put into its job (Windows) or before
//! its watchdog exists (Unix), so a grandchild it starts in that window
//! (microseconds) can escape; language servers and git start their own
//! children much later.
use std::io;
use std::ops::{Deref, DerefMut};
use std::process::{Command, ExitStatus};
#[cfg(unix)]
mod unix;
#[cfg(windows)]
mod windows;
#[cfg(unix)]
use unix::Group;
#[cfg(windows)]
use windows::Group;
/// The group a child runs in on platforms without job objects or process
/// groups: nothing beyond the child itself.
#[cfg(not(any(unix, windows)))]
struct Group;
#[cfg(not(any(unix, windows)))]
impl Group {
/// Nothing to set up.
fn prepare(_command: &mut Command) {}
/// Nothing to attach.
///
/// # Errors
/// Never.
fn attach(_child: &std::process::Child) -> io::Result<Self> {
Ok(Self)
}
/// Nothing to kill beyond the child, which [`Child::kill`] handles.
fn kill(&mut self) {}
}
/// A child process in its own kill-on-close group.
///
/// It dereferences to [`std::process::Child`] for the pipes, `id`,
/// `try_wait` and `wait`. [`Child::kill`] replaces the standard `kill` and
/// takes the whole group. Dropping it kills the group and reaps the child,
/// so a [`Child`] must be kept for as long as the process should run.
pub struct Child {
/// The process itself.
inner: std::process::Child,
/// Its job object (Windows) or watchdog (Unix).
group: Group,
}
/// Starts `command` in a new kill-on-close group (see the crate docs).
///
/// Everything else about `command` (arguments, environment, working
/// directory, stdio, Windows creation flags) is used as given.
///
/// # Errors
/// The error of [`Command::spawn`], or the error of setting up the group
/// (Windows: creating the job or assigning the process to it; Unix:
/// starting the watchdog). When the group cannot be set up, the child that
/// was already started is killed and reaped before the error is returned,
/// so it never runs unguarded.
pub fn spawn(mut command: Command) -> io::Result<Child> {
Group::prepare(&mut command);
let mut inner = command.spawn()?;
match Group::attach(&inner) {
Ok(group) => Ok(Child { inner, group }),
Err(error) => {
let _ = inner.kill();
let _ = inner.wait();
Err(error)
}
}
}
impl Child {
/// Kills the child and every process in its group, without waiting for
/// the child; call [`std::process::Child::wait`] to reap it.
///
/// Killing a child that has exited already is not an error.
///
/// # Errors
/// The error of killing the direct child, as
/// [`std::process::Child::kill`] reports it. Failing to reach the rest
/// of the group is not reported: the job (Windows) or watchdog (Unix)
/// is the only handle on it, and it is consumed either way.
pub fn kill(&mut self) -> io::Result<()> {
self.group.kill();
self.inner.kill()
}
/// Kills the group (see [`Child::kill`]) and waits for the child.
///
/// # Errors
/// The error of [`std::process::Child::wait`].
pub fn kill_and_wait(&mut self) -> io::Result<ExitStatus> {
let _ = self.kill();
self.inner.wait()
}
}
impl Deref for Child {
type Target = std::process::Child;
fn deref(&self) -> &Self::Target {
&self.inner
}
}
impl DerefMut for Child {
fn deref_mut(&mut self) -> &mut Self::Target {
&mut self.inner
}
}
impl std::fmt::Debug for Child {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Child")
.field("id", &self.inner.id())
.finish_non_exhaustive()
}
}
impl Drop for Child {
/// Kills the group and reaps the child. Errors are ignored on purpose:
/// the process may have exited already, and a destructor has no one to
/// report to.
fn drop(&mut self) {
let _ = self.kill_and_wait();
}
}

68
crates/proc/src/unix.rs Normal file
View file

@ -0,0 +1,68 @@
//! Unix: the child leads a new process group, and a watchdog kills that
//! group when Lutra's end of a pipe closes.
//!
//! The watchdog is `/bin/sh` reading its standard input, a pipe whose
//! write end only the [`Group`] holds (standard library pipes are
//! close-on-exec, so no other child inherits it). `read` returns at end of
//! file, which happens when the [`Group`] drops the pipe or when Lutra's
//! process ends for any reason, including `SIGKILL`; the watchdog then
//! sends `SIGKILL` to the group. It runs in a process group of its own, so
//! a Ctrl-C or hangup aimed at Lutra's group does not take it down first.
use std::io;
use std::os::unix::process::CommandExt;
use std::process::{ChildStdin, Command, Stdio};
/// The watchdog script: wait for end of file on stdin, then kill the
/// process group given as `$1`.
const WATCHDOG: &str = "read -r _; kill -KILL -\"$1\" 2>/dev/null";
/// The child's process group and its watchdog.
pub(crate) struct Group {
/// The watchdog process, reaped after it has killed the group.
watchdog: std::process::Child,
/// Lutra's end of the watchdog's pipe; dropping it fires the watchdog.
trigger: Option<ChildStdin>,
}
impl Group {
/// Makes the child the leader of a new process group.
pub(crate) fn prepare(command: &mut Command) {
command.process_group(0);
}
/// Starts the watchdog for the group led by `child`.
///
/// # Errors
/// The error of starting `/bin/sh`, or a missing stdin pipe.
pub(crate) fn attach(child: &std::process::Child) -> io::Result<Self> {
let mut watchdog = Command::new("/bin/sh")
.arg("-c")
.arg(WATCHDOG)
.arg("lutra-proc-watchdog")
.arg(child.id().to_string())
.stdin(Stdio::piped())
.stdout(Stdio::null())
.stderr(Stdio::null())
.process_group(0)
.spawn()?;
let Some(trigger) = watchdog.stdin.take() else {
let _ = watchdog.kill();
let _ = watchdog.wait();
return Err(io::Error::other("the watchdog has no stdin pipe"));
};
Ok(Self {
watchdog,
trigger: Some(trigger),
})
}
/// Fires the watchdog and waits until it has killed the group. The
/// results are ignored on purpose: a watchdog that is gone already has
/// nothing left to do, and the caller kills the direct child itself.
pub(crate) fn kill(&mut self) {
if self.trigger.take().is_some() {
let _ = self.watchdog.wait();
}
}
}

View file

@ -0,0 +1,77 @@
//! Windows: one job object per child with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`
//! (<https://learn.microsoft.com/windows/win32/procthread/job-objects>).
//!
//! This is the one module in Lutra that allows `unsafe`: the job object API
//! is only reachable through FFI. Every call gets valid arguments by
//! construction: handles come from `CreateJobObjectW` (owned by an
//! [`OwnedHandle`] right away) or from a live [`std::process::Child`], and
//! the limit structure is a plain C struct that is valid when zeroed.
#![allow(unsafe_code)]
use std::io;
use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle};
use std::process::Command;
use windows_sys::Win32::System::JobObjects::{
AssignProcessToJobObject, CreateJobObjectW, JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
JOBOBJECT_EXTENDED_LIMIT_INFORMATION, JobObjectExtendedLimitInformation,
SetInformationJobObject, TerminateJobObject,
};
/// The exit code a process killed with its job reports.
const KILLED_EXIT_CODE: u32 = 1;
/// The job a child runs in. Lutra holds the only handle; closing it (on
/// drop, or when Lutra's process ends) kills every process in the job.
pub(crate) struct Group {
/// The job object.
job: OwnedHandle,
}
impl Group {
/// Nothing to set on the command: the process joins its job right
/// after it starts.
pub(crate) fn prepare(_command: &mut Command) {}
/// Creates a kill-on-close job and puts `child` into it.
///
/// # Errors
/// The OS error of `CreateJobObjectW`, `SetInformationJobObject` or
/// `AssignProcessToJobObject`.
pub(crate) fn attach(child: &std::process::Child) -> io::Result<Self> {
let raw = unsafe { CreateJobObjectW(std::ptr::null(), std::ptr::null()) };
if raw.is_null() {
return Err(io::Error::last_os_error());
}
let job = unsafe { OwnedHandle::from_raw_handle(raw) };
let mut limits: JOBOBJECT_EXTENDED_LIMIT_INFORMATION = unsafe { std::mem::zeroed() };
limits.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
let size = u32::try_from(std::mem::size_of::<JOBOBJECT_EXTENDED_LIMIT_INFORMATION>())
.map_err(io::Error::other)?;
let set = unsafe {
SetInformationJobObject(
job.as_raw_handle(),
JobObjectExtendedLimitInformation,
std::ptr::from_ref(&limits).cast(),
size,
)
};
if set == 0 {
return Err(io::Error::last_os_error());
}
let assigned =
unsafe { AssignProcessToJobObject(job.as_raw_handle(), child.as_raw_handle()) };
if assigned == 0 {
return Err(io::Error::last_os_error());
}
Ok(Self { job })
}
/// Terminates every process in the job. The result is ignored on
/// purpose: the job may be empty already, and closing the handle on
/// drop kills whatever is left anyway.
pub(crate) fn kill(&mut self) {
let _ = unsafe { TerminateJobObject(self.job.as_raw_handle(), KILLED_EXIT_CODE) };
}
}

View file

@ -0,0 +1,103 @@
//! Process trees started through `lutra_proc` die with their owner.
//!
//! Each test starts `lutra-proc-helper` in a tree role: the helper starts a
//! sleeping grandchild that holds its standard output, prints `ready`
//! and sleeps. Reading that output to end of file proves that every
//! process holding it, the grandchild included, has exited. Without the
//! groups the grandchild sleeps for two minutes and the read times out.
#![allow(clippy::unwrap_used)]
use std::io::{BufRead, BufReader, Read};
use std::process::{ChildStdout, Command, Stdio};
use std::sync::mpsc;
use std::thread;
use std::time::Duration;
/// How long a test waits for a tree to go away.
const GONE_WITHIN: Duration = Duration::from_secs(15);
/// The helper in `role`, with its output piped.
fn helper(role: &str) -> Command {
let mut command = Command::new(env!("CARGO_BIN_EXE_lutra-proc-helper"));
command
.arg(role)
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::null());
command
}
/// Waits for the helper's `ready` line and returns the rest of its output.
fn ready(stdout: ChildStdout) -> BufReader<ChildStdout> {
let mut reader = BufReader::new(stdout);
let mut line = String::new();
reader.read_line(&mut line).unwrap();
assert_eq!(line.trim(), "ready");
reader
}
/// Asserts that the output reaches end of file within [`GONE_WITHIN`],
/// i.e. that no process holding it is left.
fn assert_gone(mut reader: BufReader<ChildStdout>) {
let (tx, rx) = mpsc::channel();
thread::spawn(move || {
let mut rest = Vec::new();
let _ = reader.read_to_end(&mut rest);
let _ = tx.send(());
});
assert!(
rx.recv_timeout(GONE_WITHIN).is_ok(),
"a grandchild still holds the pipe after {GONE_WITHIN:?}"
);
}
#[test]
fn hard_kill_of_the_parent_takes_its_guarded_child() {
let mut parent = helper("tree-proc").spawn().unwrap();
let reader = ready(parent.stdout.take().unwrap());
parent.kill().unwrap();
parent.wait().unwrap();
assert_gone(reader);
}
#[test]
fn hard_kill_works_when_the_parent_is_in_a_group_itself() {
let mut parent = lutra_proc::spawn(helper("tree-proc")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
std::process::Child::kill(&mut parent).unwrap();
parent.wait().unwrap();
assert_gone(reader);
drop(parent);
}
#[test]
fn kill_takes_the_whole_tree() {
let mut parent = lutra_proc::spawn(helper("tree-plain")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
parent.kill().unwrap();
parent.wait().unwrap();
assert_gone(reader);
}
#[test]
fn drop_takes_the_whole_tree() {
let mut parent = lutra_proc::spawn(helper("tree-plain")).unwrap();
let reader = ready(parent.stdout.take().unwrap());
drop(parent);
assert_gone(reader);
}
#[test]
fn a_child_that_exits_reports_its_status() {
let mut child = lutra_proc::spawn(helper("unknown-role")).unwrap();
let status = child.wait().unwrap();
assert_eq!(status.code(), Some(2));
child.kill().unwrap();
}
#[test]
fn a_missing_program_is_an_error() {
let error = lutra_proc::spawn(Command::new("lutra-proc-no-such-program")).unwrap_err();
assert_eq!(error.kind(), std::io::ErrorKind::NotFound);
}

View file

@ -1,6 +1,6 @@
# Architecture # Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4) · **Last updated:** 2026-10-22 > **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1) · **Last updated:** 2026-10-24
## Overview ## Overview
@ -18,6 +18,7 @@ crates/vfs (L2) project model, file watching, ignore rules, encodings
crates/search (L2) find in files (ignore + grep-searcher crates) crates/search (L2) find in files (ignore + grep-searcher crates)
crates/syntax (L1) tree-sitter parsing (PHP first), outlines, highlight tokens crates/syntax (L1) tree-sitter parsing (PHP first), outlines, highlight tokens
crates/text (L0) rope buffer, positions, UTF-8/UTF-16 conversion, edits crates/text (L0) rope buffer, positions, UTF-8/UTF-16 conversion, edits
crates/proc (L0) child processes that die with Lutra (job objects, process groups)
crates/testkit (—) test helpers and fixtures, tests only crates/testkit (—) test helpers and fixtures, tests only
xtask (—) ci, layers, assets, cleanroom, dev, fixtures, lints-selftest, ui-licences xtask (—) ci, layers, assets, cleanroom, dev, fixtures, lints-selftest, ui-licences
``` ```
@ -330,6 +331,17 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- Shutdown: `shutdown(self)` sends `shutdown` (waits up to 2 s), `exit`, kills after 1 s, fails what is pending with `Stopped` and reports `Stopped`; it blocks for up to about 3 s, so callers run it off the engine lock. Dropping the `Server` requests the same stop in the background. - Shutdown: `shutdown(self)` sends `shutdown` (waits up to 2 s), `exit`, kills after 1 s, fails what is pending with `Stopped` and reports `Stopped`; it blocks for up to about 3 s, so callers run it off the engine lock. Dropping the `Server` requests the same stop in the background.
- URIs (`uri`): `path_to_uri` percent-encodes everything except unreserved characters, `/` and a drive colon (`file:///C:/a%20b.php`, UNC as `file://host/share`); `uri_to_path` accepts escapes in any case, an encoded drive colon and `localhost`, and upper-cases the drive letter; bad escapes, NUL and other schemes give `None`. - URIs (`uri`): `path_to_uri` percent-encodes everything except unreserved characters, `/` and a drive colon (`file:///C:/a%20b.php`, UNC as `file://host/share`); `uri_to_path` accepts escapes in any case, an encoded drive colon and `localhost`, and upper-cases the drive letter; bad escapes, NUL and other schemes give `None`.
- Tests: the fake server `src/bin/lutra-lsp-fake.rs` (a test fixture, started via `CARGO_BIN_EXE_lutra-lsp-fake`) covers initialize, server requests, log and stderr, typed requests and errors, queueing before ready, timeout and cancel with `$/cancelRequest`, incremental and full sync (the fake applies the changes and publishes the text as a diagnostic), malformed output, crash, restart and reopen, initialize errors, giving up with the backoff sequence, shutdown and spawn errors (13 tests, about 0.5 s). `real_phpactor` is ignored and runs with `LUTRA_PHPACTOR` (path to `phpactor.phar`, `LUTRA_PHP` for PHP); it was not run in M3.2 (no Phpactor on the dev machine yet; M3.1 downloads it). - Tests: the fake server `src/bin/lutra-lsp-fake.rs` (a test fixture, started via `CARGO_BIN_EXE_lutra-lsp-fake`) covers initialize, server requests, log and stderr, typed requests and errors, queueing before ready, timeout and cancel with `$/cancelRequest`, incremental and full sync (the fake applies the changes and publishes the text as a diagnostic), malformed output, crash, restart and reopen, initialize errors, giving up with the backoff sequence, shutdown and spawn errors (13 tests, about 0.5 s). `real_phpactor` is ignored and runs with `LUTRA_PHPACTOR` (path to `phpactor.phar`, `LUTRA_PHP` for PHP); it was not run in M3.2 (no Phpactor on the dev machine yet; M3.1 downloads it).
### Child processes (H1)
`lutra_proc::spawn(Command) -> io::Result<lutra_proc::Child>` starts every external tool Lutra runs (Phpactor and the `php -v` probe now; git, `php -l` and others next) in a group the OS tears down when Lutra's process ends, even when Lutra is killed hard.
- **Windows:** one job object per child with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` (`windows-sys`). Lutra holds the only handle, so dropping the `Child` or the end of Lutra's process (the kernel closes its handles) kills the child and everything it started. Jobs nest (Windows 8+), so this works when Lutra itself runs in a job (terminal, `cargo`, CI). `crates/proc/src/windows.rs` is the only module that allows `unsafe` (FFI).
- **Unix:** the child leads a new process group; a `/bin/sh` watchdog in its own group blocks on a pipe only Lutra holds and sends `SIGKILL` to the child's group when the pipe closes (drop, kill, quit, or a `SIGKILL` of Lutra). Left behind after a `SIGKILL` of Lutra: processes that left the group themselves (`setsid`/`setpgid`, daemons), and the child if Lutra dies between starting it and starting its watchdog. Compiled and tested by CI only (no Unix machine here).
- `Child` dereferences to `std::process::Child`. `Child::kill` replaces the standard `kill` and takes the whole group; `kill_and_wait` also reaps; `Drop` kills the group and reaps.
- A child runs for a moment before it joins its job (Windows) or before its watchdog exists (Unix); a grandchild started in those microseconds can escape.
- Tests: `crates/proc/tests/process_tree.rs` starts `lutra-proc-helper`, which starts a sleeping grandchild holding the test's pipe. A hard kill of the helper (`TerminateProcess` / `SIGKILL`, with and without the helper itself in a group), `Child::kill` and drop each end the tree; the pipe reaches end of file. Without `KILL_ON_JOB_CLOSE` the hard-kill tests fail.
- The integrated terminal (portable-pty) does not use it yet. On Unix portable-pty makes the shell a session leader, and closing the PTY master on Lutra's exit hangs it up. On Windows the ConPTY host ends its clients when its pipes break; joining the shell to a job needs an adopt-by-handle API (`portable_pty::Child::as_raw_handle`), a follow-up.
### Terminal (M3.6) ### Terminal (M3.6)
- **Library:** `crates/terminal` (L3) wraps `portable-pty` (MIT; ConPTY on Windows, a Unix pty elsewhere). `Session::spawn(SpawnOptions {shell, cwd, cols, rows, env})` starts the shell with `TERM=xterm-256color`, `COLORTERM=truecolor`, `TERM_PROGRAM=Lutra`. Each session has three threads, so no call blocks the caller: a reader (16 KiB reads, `Utf8Chunker` joins a character split across reads and turns invalid bytes into U+FFFD like `from_utf8_lossy`), a writer (input queue of at most 64 pieces of 64 KiB; a full queue fails with `InputFull` instead of blocking), and a waiter that records the exit code and then closes the pty, because ConPTY reports the end of output only once the pseudo console is closed. `default_shell()`: `pwsh.exe` from `PATH` (with `-NoLogo`), then `powershell.exe`, then `%COMSPEC%`/`cmd.exe` on Windows; `$SHELL` or `/bin/sh` on Unix. - **Library:** `crates/terminal` (L3) wraps `portable-pty` (MIT; ConPTY on Windows, a Unix pty elsewhere). `Session::spawn(SpawnOptions {shell, cwd, cols, rows, env})` starts the shell with `TERM=xterm-256color`, `COLORTERM=truecolor`, `TERM_PROGRAM=Lutra`. Each session has three threads, so no call blocks the caller: a reader (16 KiB reads, `Utf8Chunker` joins a character split across reads and turns invalid bytes into U+FFFD like `from_utf8_lossy`), a writer (input queue of at most 64 pieces of 64 KiB; a full queue fails with `InputFull` instead of blocking), and a waiter that records the exit code and then closes the pty, because ConPTY reports the end of output only once the pseudo console is closed. `default_shell()`: `pwsh.exe` from `PATH` (with `-NoLogo`), then `powershell.exe`, then `%COMSPEC%`/`cmd.exe` on Windows; `$SHELL` or `/bin/sh` on Unix.
@ -394,7 +406,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- After an edit: 1.8 s and 2.7–2.9 s, including Phpactor's 1 s debounce. - After an edit: 1.8 s and 2.7–2.9 s, including Phpactor's 1 s debounce.
- Without the adjustments: no diagnostics within 180 s. - Without the adjustments: no diagnostics within 180 s.
- **Known gaps:** - **Known gaps:**
- A Phpactor process outlives Lutra when Lutra is killed, or when a test process exits right after dropping the engine. There is no job object or kill-on-close yet; that is a `lutra-lsp` follow-up. - ~~A Phpactor process outlives Lutra when Lutra is killed.~~ Fixed by H1: Phpactor starts through `lutra_proc::spawn` (see Child processes).
- `window/showMessage` and `logMessage` are dropped, and server-initiated progress is not shown. - `window/showMessage` and `logMessage` are dropped, and server-initiated progress is not shown.
- **Tests:** - **Tests:**
- `crates/engine/tests/lsp.rs` has 10 tests against `lutra-lsp-fake`: sync incl. UTF-16 and CRLF edits, diagnostics list/clear, reload resync, requests after edits, project close, restart, quit, missing server, crash and give-up, no server without a project, and a proptest of random edits. The ignored `real_phpactor_reports_diagnostics` runs with `LUTRA_PHPACTOR=<phar>`. - `crates/engine/tests/lsp.rs` has 10 tests against `lutra-lsp-fake`: sync incl. UTF-16 and CRLF edits, diagnostics list/clear, reload resync, requests after edits, project close, restart, quit, missing server, crash and give-up, no server without a project, and a proptest of random edits. The ignored `real_phpactor_reports_diagnostics` runs with `LUTRA_PHPACTOR=<phar>`.
@ -544,6 +556,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 2026-10-24 | minor | H1: `crates/proc` (L0), child processes in kill-on-close groups (Windows job objects, Unix process groups with a watchdog); Phpactor and the PHP probe use it |
| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) | | 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) |
| 2026-10-22 | minor | M3.4: code assistance (`lsp.completion`, `lsp.hover`, `lsp.signatureHelp` on pending outcomes; editor completion source, hover, signature help, safe Markdown, assist UI commands), Phpactor latency and resources | | 2026-10-22 | minor | M3.4: code assistance (`lsp.completion`, `lsp.hover`, `lsp.signatureHelp` on pending outcomes; editor completion source, hover, signature help, safe Markdown, assist UI commands), Phpactor latency and resources |
| 2026-10-22 | minor | M3.5 step 1: pending outcomes (`Pending`, `Engine::resolve`, `run_waiting`), `engine_execute_waiting` / `runWaiting` | | 2026-10-22 | minor | M3.5 step 1: pending outcomes (`Pending`, `Engine::resolve`, `run_waiting`), `engine_execute_waiting` / `runWaiting` |

View file

@ -1,6 +1,6 @@
# Gaps # Gaps
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G14 English UI catalog in place · **Last updated:** 2026-10-22 > **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename, Phpactor dies with Lutra); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G14 English UI catalog in place · **Last updated:** 2026-10-24
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated. Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated.
@ -44,12 +44,13 @@ Known smaller items from M0:
- `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that. - `ui.screenshot` captures the screen region of the window, so covering windows appear in the image; a webview-native capture would avoid that.
- `cargo xtask fixtures` needs Composer, which the M0 machine does not have. - `cargo xtask fixtures` needs Composer, which the M0 machine does not have.
G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. Still open: slow first indexing on Windows (Phpactor advances one step per stdin message, so a 2,000-class project takes ~65 s before completion is useful), PHP lint syntax errors on Windows, quick-fixes, and killing a Phpactor process left behind when Lutra itself is killed. G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framing over stdio (32 MiB cap, malformed messages dropped and logged, fuzzed), `initialize` with UTF-16 positions, typed requests with timeouts and `$/cancelRequest`, answers to server requests, supervision with backoff restarts (give up after 5 crashes in 2 min) and reopening of documents, incremental document sync from `lutra_text` edits, all tested against a fake server. M3.3 wired it into the engine (one Phpactor per project on its own thread, ordered document sync, `lspStatus`) and shows Phpactor's diagnostics as editor underlines and in a Problems tab. It was checked against the real Phpactor on Windows, which needed three workarounds: a keep-alive tick, in-process diagnostics and a polling watcher (see `docs/architecture.md`). M3.4 added completion, hover and signature help in the editor (Phpactor's answers, Lutra's triggers, safe Markdown, measured 61–109 ms per completion while typing on Windows). M3.5 added go to definition (F12, Mod+click, a picker for several), find references (a References tab) and rename (F2, an inline field; open buffers dirty and undoable, closed files written atomically, edits outside the project refused), all through Phpactor without blocking the engine; rename has no preview list yet, and the editor's undo does not revert closed files it wrote. H1 (C5) put Phpactor into a kill-on-close group (`crates/proc`: a job object on Windows, a process group with a watchdog on Unix), so it no longer outlives Lutra, even when Lutra is killed. Still open: slow first indexing on Windows (Phpactor advances one step per stdin message, so a 2,000-class project takes ~65 s before completion is useful), PHP lint syntax errors on Windows, quick-fixes.
## Revision history ## Revision history
| Date | Change | Summary | | Date | Change | Summary |
|---|---|---| |---|---|---|
| 2026-10-24 | minor | G6: Phpactor no longer outlives Lutra (H1) |
| 2026-10-22 | minor | G6 shrunk: definition, references, rename (M3.5) | | 2026-10-22 | minor | G6 shrunk: definition, references, rename (M3.5) |
| 2026-10-22 | minor | G6 shrunk: completion, hover and signature help (M3.4) | | 2026-10-22 | minor | G6 shrunk: completion, hover and signature help (M3.4) |
| 2026-10-21 | minor | G6 shrunk: engine wiring and diagnostics (M3.3) | | 2026-10-21 | minor | G6 shrunk: engine wiring and diagnostics (M3.3) |