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

View file

@ -1,6 +1,6 @@
# 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
@ -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/syntax (L1) tree-sitter parsing (PHP first), outlines, highlight tokens
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
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.
- 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).
### 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)
- **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.
- Without the adjustments: no diagnostics within 180 s.
- **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.
- **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>`.
@ -544,6 +556,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| 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.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` |