[raphaelvigee]

Stacked on #516. Spec: https://claude.ai/artifact/SzmPFWNomk87UJVGSQy4dw

On a terminal, heph run //x now runs an entrypoint behind a PTY heph owns, with no log and no redaction. --raw drops the TUI and heph's wrapping, and the tool inherits the caller's fds. A redirected or background run inherits too, so pipes stay byte-exact. On a build target, --raw only changes the display, and a build target's --shell loses its log and redaction and follows a live resize.

HEPH_LOG=entrypoint_mode=debug heph run //x says which mode a run took, and why.

Release note

heph run on an entrypoint now runs the tool behind a PTY heph owns when stdin, stdout and stderr are all your terminal and the run is the foreground job. Ctrl-Z does nothing on a plain tool there. --raw is the new way out: no TUI, the tool inherits your fds and gets real Ctrl-Z, with two signal limits; any redirected or background run inherits too. On a build target, --raw only prints the action's output plainly. Credentials: no entrypoint run and no build target's --shell is logged or redacted, so env in a build target's --shell now shows tokens that used to read [redacted]. Stdin: piped or < file stdin no longer reaches a plain heph run build, because it was not part of the cache key and could poison an artifact. See docs/ENTRYPOINTS.md.

Verification

CI runs under ci/force-ci because this behaviour is platform-specific.

• Decision 5's Linux spike passed. plain_tool_under_ctrl_z_keeps_running, tool_handling_sigtstp_sees_it and self_sigstop_suspends_and_resumes ran and passed on linux/amd64 and linux/arm64 (run 41211774247), so Linux matches the macOS spike.
• Board review on a853179, with verdicts in the spec:
  • code-quality BLOCKED: heph could stop itself with nobody to resume it (ssh -t, tmux, docker exec). Fixed; round 2 found the docker exec hole, fixed with a unit test and no further round.
  • hermeticity NOT HERMETIC: piped stdin reached a cached build on macOS, through the macOS TUI fix. A plain build now gets stdin only when fd 0 is a terminal; round 2 HERMETIC WITH EXEMPTIONS (typed keystrokes, pre-existing).
  • feature-quality PASS WITH FOLLOW-UPS, compatibility COMPATIBLE, product-vision SHIP WITH CHANGES; applied.
  • Re-reviewed on 8437e92: code-quality PASS, compatibility COMPATIBLE, product-vision SHIP, feature-quality PASS WITH FOLLOW-UPS (minors applied in 5b98e22, not re-reviewed).
• docker exec, measured on linux/arm64 in a container: PPid: 0 confirmed. A tool that stops itself is continued, with heph as the direct exec'd command. Exit code and termios were captured only with an sh -c between them, and no pre-fix build was compared.
• Performance, macOS only, 1 GiB to a real PTY: default 20.8 s, down from 33.4 s after the review; --raw 8.3 to 9.2 s; by hand 8.9 s. So --raw adds nothing per byte, and the default costs about 2.3x. Warm true: --raw 18.3 ms, default 20.6 ms, by hand 2.8 ms. Warm gopls version, no tty: --raw 32.7 ms, feat: entrypoints — invoke a target in your world through the driver's ordinary run #516 32.5 ms (within noise), by hand 14.8 ms. Linux/arm64 in an OrbStack VM, 1 GiB to a PTY, n=5, so only the ratios transfer: default 8.45 s, --raw 4.28 s, by hand 4.81 s. Default is about 2.0x --raw there, and --raw matches by hand within noise. Not measured on real Linux hardware.
• A CI failure that turned out to be a test race: local_runner_shell_keeps_working failed once on darwin/arm64. bash can lose a Ctrl-C; reproduced with added jitter on a bare PTY with no heph (19/800). The test now resends it, 1000/1000 jittered, so it would no longer catch a one-off dropped Ctrl-C.

Per-platform differences, for the user to accept or not

1. Drain on macOS has no window. Measured on macOS: when the session leader exits, the master gets EOF within milliseconds, and a surviving daemon's writes then fail with EIO. So a daemon's late output is lost at once, with no drain limit and no warning. On Linux, default_run_drain_is_bounded passes with the limit and the warning's byte count asserted: heph waits up to the limit and warns. stop_during_drain_is_ignored has a window only on Linux too. Avoiding this would need a helper process in the session.
2. \r\r\n on macOS. XNU emits one every 4095 bytes once a slave's queue fills, on a plain PTY with no heph involved. It renders the same. The two output-complete tests collapse it on macOS only; Linux keeps the exact comparison. Clamping the baud rate would remove it but lie to tools, so that was not done.
3. crossterm use-dev-tty, macOS only. kqueue rejects /dev/tty, so a redirected stdin killed the TUI and the tool never ran. Same behaviour on both OSes by a different implementation.

Departures from the spec

• raise(SIGSTOP), not kill(getpid(), SIGSTOP), in Stops step 4. "That call returning is the resume" needs the stop to land before the return; on Linux kill may return on a worker thread first. Reasoned, not measured.
• pty_fallback_warns_when_plugin_offers_none is in run.rs and crates/e2e/tests/entrypoint.rs, not plugin-exec: the fallback is host and engine logic.
• Driver::supports_shell is a new defaulted trait method, so the engine can gate on the driver that spawns.
• Added beyond the table: a test-only HEPH_PTY_DRAIN_MS, as the spec's "tests can inject the limit" needs; a test-only HEPH_PTY_OPEN_FAILS; a cdylib stop/fg test.
• entrypoint_kill_under_a_terminal now passes --raw, as the spec says: its limit belongs to the shared group.
• timeout at an interactive shell: job control makes it a group leader and the foreground job, so timeout 5 heph run //x under bash -i takes the PTY path. Under a script it inherits, as the spec says. Docs state which.

Open items settled by implementation

• Drain limit: DRAIN_DEADLINE, 500ms.
• kill -TSTP <heph>: takes the same stop path. The handler lasts for the process, so one after the tool exits does nothing.
• An entrypoint's --shell with no foreground terminal: never raw, and a stop just continues the tool.

Piped stdin reaching EOF only stops the pump; no VEOF is sent, so a piped --shell tool may wait. The spec is silent on this, and the old pump did the same.

Left for the user (in the spec's Open)

• A live resize cannot reach a tool under oci.
• File the remaining stdin hole, typed keystrokes reaching a cached build, as an issue.
• Whether to write the execve spec.

Known CI problem, not from this PR

Test linux/arm64 can fail in plugingo-e2e with No space left on device. It failed three times at 438dc90 and passed at 5b98e22 with the same code for that job; the head commit touched only a bin-e2e fixture. The user sent this to a separate session.

Decided by the user, 2026-10-31

• feat: entrypoints — invoke a target in your world through the driver's ordinary run #516's SIGKILL race is accepted: heph killed between spawning a tool and registering it orphans the tool. The test now waits until the tool is tracked (0d085a7, on feat: entrypoints — invoke a target in your world through the driver's ordinary run #516).

• Accepted: macOS late daemon output lost with no warning; macOS \r\r\n on long PTY output; a fatal signal to heph (SEGV, BUS) or an abort across the plugin seam leaving the terminal raw until reset.

• The panic hook does not restore a PTY session's terminal, because it would also fire on panics tokio catches and cook the terminal under a live tool. Uncaught panics rely on Drop; a panic that aborts leaves the terminal raw until reset.

🤖 Generated with Claude Code

[raphaelvigee]

Follow-ups filed: #526 (oci terminal and resize) and #527 (typed keystrokes reaching a cached build). The execve spec is deferred. The macOS use-dev-tty difference is accepted.