fix: subagent hangs — bash timeouts, process-group kill, watchdogs

[Emasoft]

fix: subagent hangs — bash timeouts, process-group kill, watchdogs

Emergency diagnosis (RC1–RC4, verified)

• RC1 — ShellTool bash unbounded and cancel-immune. internal/tool/implementations.go:370-373 ran the command with the raw context and no deadline; internal/tool/shell_command_unix.go:31 used bare exec.CommandContext, which kills only the direct child. A grandchild that inherited bash's stdout/stderr pipes kept CombinedOutput's Wait blocked forever — even after cancellation. Nothing bounded a never-exiting command at all.
• RC2 — parent blocked with no notification channel. The parent blocks synchronously inside the spawn_subagent tool call; its only notification is the runner's return. When a child hung (or was killed while its bash had spawned a grandchild), the parent had no budget, no termination-cause classification, and no way to learn what the child had been doing.
• RC3 — LLM clients had Timeout: 0. internal/client/client.go set no client timeout; a provider that accepted the request and then streamed nothing (half-open connection, stalled backend) blocked scanner.Scan() for the OS TCP lifetime, indistinguishable from "thinking".
• RC4 — bare exec.Command in git/mcp and blocking child event sends. internal/git/* shelled out with no bound; a credential prompt on an interactive terminal or an askpass helper hung the git tools forever. internal/mcp/client.go was unbounded exec. internal/orchestrator/base.go sent every event (streaming deltas, transient statuses) with a blocking channel send, so a stalled TUI consumer wedged the whole run loop.

The four fixes

1. fix(tool) (eda9326) — newShellCommand mirrors the proven hooks.go pattern: 10-minute default timeout (test-overridable via SetShellTimeout), Setpgid + whole-process-group SIGKILL on cancel (unix), taskkill /T /F (windows), WaitDelay = 5s so pipe-holding descendants can never block Wait. Timeout surfaces partial output as a real error.
2. fix(orchestrator) (b35a927) — the runner bounds each subagent with a new --subagent-timeout flag (default 24h, 0 = unlimited; also configurable via the subagent-timeout config.json entry, explicit flag > config > default), classifies the termination (time budget exhausted / cancelled or killed / crashed) and, on abnormal termination, writes a pruned transcript and returns a tool result (see below) instead of an opaque error.
3. fix(client) (21371b6) — a 120s stream idle watchdog (test-overridable via SetStreamIdleTimeout) cancels a silent stream so the failure surfaces through the normal retry tier; non-stream ChatCompletion/Completion/HealthCheck get a 5-minute bound (SetRequestTimeout).
4. chore (451bd0b) — every git exec gains a 60s bound plus GIT_TERMINAL_PROMPT=0 / GIT_ASKPASS=echo so credential lookups fail fast instead of hanging; the MCP server subprocess lifetime is documented as intentionally unbounded (owned by the SDK transport); child streaming ContentEvents and transient "thinking" statuses are now non-blocking with a drop counter reported at turn end, while terminal status events and ChildAddedEvent stay blocking (guaranteed consumers — the TUI state machine and the child event-forwarder setup depend on them).

Transcript feature — what the parent receives

On abnormal termination (budget exhausted, killed, or crashed) the parent's spawn_subagent tool result becomes:

The <type> subagent terminated abnormally (<cause>).
Full pruned transcript: /abs/path/to/<child-id>-transcript.md
Last actions:
<last assistant action or tool call, 500-char preview>

The transcript is pruned: system→500 B, user→2000 B, assistant→4000 B, tool results→2000 B head with a […truncated…] marker, tool-call args→500 B, reasoning content dropped, image/attachment parts → placeholders (no base64 ever), and a 64 KB total cap that keeps the header + first 2 + last 6 messages (the tail is what resuming needs). Written 0600 next to the child's own history (cache-dir fallback), so the parent can read it and resume without redoing the work.

Test evidence

• Grandchild-pipe regression: internal/tool/shell_timeout_test.go::TestShellTool_CancelReturnsDespiteGrandchildHoldingPipes — (sleep 300 &) leaves a pipe-holding grandchild; pre-fix Execute blocked forever after cancel, post-fix it returns < 5s. Plus TestShellTool_TimeoutKillsHangingCommand and TestShellTool_TimeoutLeavesNoProcesses (pgrep-verified process-group cleanup).
• Stream watchdog: silent-server abort (~5s, not OS-lifetime) and a slow-but-active stream (300 ms lines across a watchdog tick) is never killed; non-stream silent server returns via context.DeadlineExceeded.
• Orchestrator: TestBaseOrchestrator_ExecuteDoesNotDeadlockWhenEventConsumerStalls — 150-chunk stream with no event consumer; progress sends drop (counted) instead of deadlocking on the 101st send, terminal sends still delivered, full content still accumulated.
• Client idle-watchdog + transcript pruning table tests (image strip, per-role caps, reasoning drop, 64 KB head/tail overflow, rune-safe truncation, path fallback) all pass under -race.
• A 30x repeated-run stress of the regression suite was not executed in this session; the race-detector full suite was run three times across the change (see flake note) with the new tests green every time.

Environmental plugin flake note (pre-existing, unrelated)

late/internal/plugin fails with 4 known environmental tests on this machine — reproduced identically on a clean main checkout (de0d922) via a throwaway worktree: TestRunHook_ProcessGroupKillsChildrenOnCancel, TestHandlePluginRemove_PurgesStaleSkillSymlink, TestHandlePluginRemove_PreservesSiblingSkillSymlink, TestRegisterPluginSkills_PreservesSameNamedSkills (HOME/XDG + process-spawn timing in this environment; the branch touches nothing in internal/plugin). One full-suite run additionally showed TestHandleCommand_ConcurrentWithWriters (load-timing) which did not reproduce in two package-alone runs.

Independence from #127

This branch is main-based; its fixes are independent of PR #127's changes. No rebase or conflict with #127 is expected on either side.

Update: subagent-timeout is now config.json-configurable (subagent-timeout), default 24h.

[mlhher]

Thank you for your contribution. I will take a look at it and evaluate it.