The watchdog mechanism was complete but had an inconsistency:
main.rs used exit code 3 for timeout errors while ClaudePrintError::Timeout.exit_code()
returned 124 (GNU timeout convention). Now uses the proper exit code from the error type.
This ensures timeout errors exit with the standard code 124, matching GNU timeout
behavior and making error handling consistent for callers (marathon loop/NEEDLE).
This improvement ensures that when a watchdog timeout occurs, the event
loop wakes up immediately (via self-pipe write) rather than waiting for
the poll timeout. This allows for faster and more responsive cleanup on
timeout, ensuring temp dirs and FIFOs are removed promptly.
Co-Authored-By: Claude <noreply@anthropic.com>
- Add cleanup_performed flag to HookInstaller for idempotent cleanup
- Add Drop implementation to HookInstaller for automatic cleanup
- Enhance cleanup() to explicitly remove both FIFO and temp directory
- Ensure temp dirs are cleaned up on normal exit, error, timeout, signals, and panic
- cleanup_orphans() already called at startup to sweep stale temp dirs
Co-Authored-By: Claude <noreply@anthropic.com>
Implement a complete watchdog timeout system that ensures hung child
processes are terminated cleanly with proper diagnostics and cleanup.
Features:
- PTY first-output timeout (default 90s): detects if child produces no PTY output
- Stream-json first-output timeout (default 90s): detects if child produces no stream-json events
- Overall session timeout (default 3600s): prevents indefinite hangs
- Stop hook watchdog timeout (default 120s): detects if Stop hook doesn't fire after prompt injection
Timeout handling:
- Sends SIGTERM to child process when timeout fires
- kill_child() ensures SIGTERM → SIGKILL sequence (2s grace period)
- Writes clear diagnostic to stderr indicating timeout type
- Emits stream-json error event for downstream consumers
- CleanupGuard ensures temp dir/FIFO cleanup on all exit paths
- Returns Error::Timeout and exits non-zero (code 3) for retry loop
Fixes:
- Pass temp_dir_path to Watchdog so stream-json monitoring works correctly
- Remove unused constants (duplicates of watchdog module defaults)
- Improve mock-claude binary path resolution for workspace builds
This prevents the indefinite hang that occurs when Claude Code wedges
during session initialization or tool use, ensuring marathon loops and
NEEDLE can retry cleanly instead of blocking forever.
Bead-Id: bf-2f5
Root cause: Child claude hangs at startup when global settings containing
hooks (SessionStart, SessionEnd, etc.) are inherited despite creating a
temp settings.json with only a Stop hook.
When --settings=<temp_path> is passed without --setting-sources=, Claude Code
merges temp settings with global settings. Global hooks fire and may hang,
causing the child to never produce output and the first-output timeout to fire.
Fix: Always pass --setting-sources= to child claude (src/session.rs:127-129)
to prevent global settings inheritance. This ensures ONLY the temp settings.json
is loaded, preventing any global hooks from causing hangs.
Evidence: Documented in notes/bf-2u1-findings.md and notes/bf-2u1-investigation.md
Related beads:
- bf-2w7: temp dir and FIFO cleanup
- bf-3ag: session implementation
Update all call sites to include the new first_output_timeout_secs parameter:
- src/main.rs: pass None for default first-output timeout
- tests/watchdog.rs: pass None in both watchdog tests
The prior commit added the 5th parameter but missed updating the callers,
causing compilation errors.
Co-Authored-By: Claude <noreply@anthropic.com>
Bead-Id: bf-2w7
- Add cleanup_orphans() to HookInstaller: sweeps stale claude-print-* dirs on startup
- Add cleanup() method to HookInstaller: explicitly removes FIFO and temp dir artifacts
- Add CleanupGuard struct in session.rs: ensures cleanup via Drop on all exit paths
- Call cleanup_orphans() in HookInstaller::new() on each invocation
This prevents orphaned temp directories from accumulating after crashes,
timeouts, or signal interruptions.
Co-Authored-By: Claude <noreply@anthropic.com>
Bead-Id: bf-2w7
These flags were parsed by the CLI but never added to claude_args,
so headless callers (e.g. marathon-coding) would hang on interactive
tool-use approval prompts. Also forward allowedTools/disallowedTools
for completeness.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Bug 1 (event_loop.rs): poll(-1) blocked forever when TUI went silent;
startup timer never fired so prompt was never injected. Fixed: poll(50ms)
+ empty-slice tick so poll_timers() runs on every iteration.
Bug 2 (session.rs): read_fd from open_fifo_nonblock() was dropped
immediately after as_raw_fd(), closing the fd the event loop was polling.
Fixed: store both (_fifo_read, _fifo_keeper) to keep both alive.
Bug 3 (pty.rs): child inherited CLAUDE_CODE_SESSION_ID from parent, so
it wrote events into the parent transcript and skipped Stop hook dispatch.
Fixed: unsetenv(CLAUDE_CODE_SESSION_ID) in child after fork; preserve
CLAUDECODE=1 and CLAUDE_CODE_ENTRYPOINT=cli.
Bug 4 (session.rs): empty-slice timer ticks were fed to startup.feed()
which reset last_output_at, preventing idle timer from ever firing.
Fixed: guard startup.feed() and terminal.feed() from empty slices.
Bug 5 (session.rs): handle.join() blocked main thread for up to
cli.timeout (default 3600s) on any early exit, because the timeout thread
sleeps for the full duration. Also, waitpid blocked forever if child
ignored SIGTERM. Fixed: drop(timeout_thread) to detach; add kill_child()
helper (SIGTERM → 2s wait → SIGKILL) used on all cleanup paths.
All five confirmed fixed: claude-print "what is 2+2?" → "4", exit 0,
cc_entrypoint=cli in session JSONL (subscription billing verified).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add SessionResult struct with transcript, claude_version, duration_ms
- Implement Session::run() with full signature and PTY session orchestration
- Add resolve_claude_version() using Command::new(claude_bin).arg("--version").output()
- Add pub mod session to lib.rs
- Include unit tests for version resolution with mock binaries
Co-Authored-By: Claude <noreply@anthropic.com>
Complete implementation of error.rs with:
- Full Error enum covering all error types (PTY spawn failures, hook
setup, parse failures, timeout, interruption, binary resolution,
version checks, terminal errors, and child process errors)
- Proper error propagation with user-friendly messages
- ClaudePrintError for user-facing errors with exit codes and JSON
subtypes
- 18 unit tests covering all error variants and conversions
Fixes bead bf-46v
- Add SIGINT_RECEIVED static flag and sigint_handler signal handler
- Install SIGINT handler in relay() to catch Ctrl-C presses
- Forward SIGINT to child process in relay loop using kill()
- Restore default SIGINT handler on exit
- Update error types to use specific PTY errors (OpenptyFailed, ForkFailed, SignalHandlerFailed, WaitpidFailed)
This implements key invariant #3 from AGENTS.md: pressing Ctrl-C must reach
the claude child process, not just terminate claude-print.
Co-Authored-By: Claude <noreply@anthropic.com>
Adds emitter.rs with three output format handlers and stream-json reader thread,
ClaudePrintError enum with exit codes and JSON subtypes to error.rs,
and 13 unit tests in tests/emitter.rs covering all plan requirements.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implements src/transcript.rs: lenient JSONL parsing, message.id dedup
with usage-fingerprint fallback, text extraction from ContentBlock arrays,
40×50ms retry loop for Stop-before-JSONL races (PO-5), and last_assistant_message
fallback. All 18 tests in tests/transcript.rs pass; AS-6 verified with
MOCK_DELAY_JSONL=100.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add src/poller.rs with FIFO O_NONBLOCK open (read-end + keeper write-end),
Stop hook JSON payload parsing, transcript path derivation via cwd slug,
and StopInfo resolution. Wire poller into EventLoop via add_fifo_fd() which
was already present in event_loop.rs from Phase 3.
Update mock-claude to emit proper JSON Stop payloads (with and without
transcript_path via MOCK_OMIT_TRANSCRIPT_PATH=1) and update the pty_integration
assertion to match.
Tests test_stop_hook_fires and test_missing_transcript_path_derived both pass.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Prompts exceeding INLINE_PROMPT_MAX (32 KB) are written to a NamedTempFile
and a shell $(< path) read command is injected via bracketed paste instead
of the raw bytes, avoiding PTY pipe-buffer saturation.
Adds four unit tests: threshold boundary (inline), threshold+1 (file relay),
temp-file content verification, and end-to-end state-machine coverage.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
After trust-dismiss fires, the post-dismiss wait is now an idle-gap:
injection fires only after idle_gap_ms of uninterrupted silence.
Any PTY output chunk resets the gap via last_output_at, preventing
premature injection during TUI redraws after the dismiss CR.
- Rename POST_DISMISS_IDLE_MS → DEFAULT_POST_DISMISS_IDLE_MS (pub const)
- Add idle_gap_ms field to StartupSeq; expose via with_idle_gap() ctor
- TrustDismissed timer now uses last_output_at instead of trust_dismiss_at
- Reset last_output_at when entering TrustDismissed via idle-fallback path
- Add three unit tests: resets on output, fires after silence, no double-fire
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implements StartupSeq with scan_line() that detects 2+ trust keywords
("trust", "Allow", "continue", "folder", "permission", "proceed") on a
PTY output line and returns CR to dismiss the dialog. Includes idle
fallback (0.8 s after 200+ bytes) and hard timeout (45 s / <200 bytes →
HardTimeout). Phase 2 injects the prompt via bracketed paste after a
2 s post-dismiss idle.
11 test_trust_dialog_* integration tests cover keyword match, threshold,
case sensitivity, chunk-boundary assembly, one-shot dismiss, and CR- vs
LF-terminated lines. 12 unit tests in startup::tests cover scan_line
and feed() in isolation.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implements EventLoop with master_fd + self_pipe_read as the initial 2-fd
pollfd Vec. add_fifo_fd() pushes the stop FIFO fd at PROMPT_INJECTED. run()
dispatches PTY output chunks to a callback and returns ExitReason on child
exit (EIO), FIFO payload, or self-pipe interrupt. Both required tests pass:
test_event_loop_reads_pty_output and test_event_loop_detects_child_exit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Install a SIGWINCH handler that sets a static AtomicBool; the relay loop
re-issues TIOCSWINSZ on the master fd each time it fires.
- relay() poll-loops over the master fd and stdin, copying master output to
stdout and stdin input to the master fd, with 100 ms timeout so SIGWINCH
is handled promptly on EINTR.
- Loop exits on EIO/EOF/POLLHUP from the master fd (slave side closed).
- waitpid() at the end of relay() surfaces the child exit code (or
128+signum for signal termination).
- New tests: master_fd_carries_child_stdout (acceptance criterion),
relay_echo_exits_zero_and_produces_output, relay_surfaces_nonzero_exit_code.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Change spawn() to spawn(cmd, args): on the parent side set the PTY
window size via TIOCSWINSZ mirroring stdin or defaulting to 80x24; on
the child side call execvp with the given command after login_tty.
Update the test to exercise /bin/true through the full exec path.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds PtySpawner struct that calls openpty() for master/slave fds, forks,
and runs login_tty on the child side before it exits. Fixes nix feature
flag (pty module is gated by `term`, not a `pty` feature in nix 0.29).
Adds mock-claude workspace stub so the workspace resolves cleanly.
Unit test: fork_and_login_tty_does_not_panic passes (child exits 0).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
