Repository navigation
Start terminals without forking the server - #250
krassowski wants to merge 26 commits into
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Unbounded waitpid() calls can freeze terminal creation beyond EXEC_TIMEOUT; both startup waits need deadline enforcement, termination, and asynchronous reaping of overdue processes.
1 open issue
What changed in this PR
Moves POSIX terminal startup to a small os.posix_spawn() helper, avoiding server-fork hazards in multithreaded Jupyter servers while retaining compatibility fallbacks.
Changes:
- Adds helper-based startup with environment transfer, terminal setup, signal handling, and startup error reporting.
- Retains fork fallback and adds the
PTYPROCESS_USE_FORKoverride. - Adds regression coverage and updates documentation and test configuration.
| File | Description |
|---|---|
tests/spawn_test.py |
Tests helper startup, terminal behavior, errors, cleanup, and fallbacks. |
tests/fork_hazards_test.py |
Tests protection against fork-related deadlocks and finalizer side effects. |
terminado/management.py |
Selects helper or fork startup and updates fallback environment and signal handling. |
terminado/_spawn.py |
Implements helper availability checks, spawning, communication, and cleanup. |
terminado/_spawn_helper.py |
Configures the terminal, signals, and descriptors before executing the command. |
README.md |
Documents helper startup, fallback conditions, and the forced-fork option. |
pyproject.toml |
Adjusts warning filters, coverage exclusions, and helper lint exceptions. |
Review effort: Balanced
05fd840 to
3a954ba
Compare
|
Made a separate PR to drop 3.10, we can remove it from here once the other is merged, I just don't want to spend time fixing test on a version we won't support. |
spawn() blocked on the error pipe until the helper called exec. A chdir() into a stalled network mount, or any process that keeps the pipe open, then froze the whole server. spawn() now waits at most EXEC_TIMEOUT seconds, then kills the helper, reaps it in a daemon thread and raises TimeoutError.
The helper decodes its arguments with the locale in env, but encoded the file name of an error as UTF-8, and spawn() decoded it as UTF-8. With a Latin-1 locale in env, a missing cwd named café came back as café. The helper now uses os.fsencode() and spawn() uses os.fsdecode(), so the bytes of the name reach spawn() unchanged. A test would need a non-UTF-8 locale, not available on CI so no test here.
No longer needed 🎉
On macOS, the output of a helper that exits before exec is lost when the last slave of the pty is closed. The parent closed its slave right after posix_spawn(), so the error message lost the last line of the traceback. Keep the slave open until that output has been read. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Assign the duration to `elapsed` before asserting, so that the rewritten assertion in the CI log shows a readable number. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
3a954ba to
d4dc269
Compare
|
Rebase on main with the help of haiku, the test should be passing, This does not contain the previous commit about dropping 3.10. |
|
I renamed @krassowski I'll let you review my changes if you wish and will merge next monday otherwise. |

References
Details
os.posix_spawn()helper instead offork()pexpect/ptyprocess#89Code changes
python -I -Shelper launched withos.posix_spawn(), so no server code runs in the child (option 1 in Start terminals without forking the server #249).envtoos.execve()through a pipe.setsid(), so a Ctrl-C to the server does not stop a terminal that is starting.os.posix_spawn()), in frozen apps, and when a first test start of the helper withsys.executablefails or takes longer than 30 s.TimeoutErrorwhen the shell has not started after 30 s.OSErrorwith the exit code and the last line that the helper printed, when the helper exits beforeexec.envto the fork unchanged, so thatenv=Nonegives the shell the environment of the server on that path too.User-facing changes
Before: opening a terminal forks the server, and extension and library code runs in the copy before the shell starts (#249).
After: no server code runs before the shell starts.
PermissionError.jupyter lab &in a script.The table gives medians of 30 opens on Ubuntu 26.04 with Python 3.15:
Backwards-incompatible changes
None
AI usage