hil-contract: a background hil_remote.py launch is killed at the Bash default 10 min timeout

Open Beginner friendly
  • Is something wrong?
#4,482 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
84/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
bash, github, python
Domain
testing, tooling

Research direction

Read .claude/skills/hil-contract/SKILL.md at “Timing” and check how it describes the background hil_remote.py launch and the foreground wait timeout. Update the background launch instruction with an explicit timeout that covers the stated pool guard plus staging; keep the existing wait timeout guidance. Done when the recipe gives the launch a timeout long enough for a full HIL run.

Written by the indexing model from the issue text.

Description

follow-up Prio 📌

Found while babysitting #4028; the topic is outside its scope (the PR changes usbd/usbh/ports, not HIL tooling).

Problem

.claude/skills/hil-contract/SKILL.md "### Timing" tells an agent to launch hil_remote.py --run-id ... with "Bash run_in_background: true" and then wait, but names no timeout for the background launch. Claude Code's Bash tool gives a background command a default timeout of 600000 ms (10 min) and stops it at that limit. The same section says the pool guard (HIL_POOL_TIMEOUT) is 3600 s, so a run can legitimately exceed 10 min, and a full-roster run already sits right at the default.

Evidence

2026-11-10, ci.lan, run id hil-4028-r3-base-a (hil-operator, full 28-board tinyusb.json replay of CI artifact run 42797997766):

HIL_SHUFFLE_SEED=1794306834 python3 .claude/skills/hil-contract/scripts/hil_remote.py --run-id hil-4028-r3-base-a -B cmake-build/ci-42797997766-base --retry 1 --exclude-flasher esptool --exclude-flasher openocd_esp
  • Launched in the background without a timeout; killed at ~10 min. The closed ssh pipe aborted the rig's hil_test.py ("HIL run aborted: a worker raised BrokenPipeError"), hil_remote.py wait returned dead, and no report came home.
  • The same full-roster dispatch on the PR firmware (run hil-4028-r3-pr-b) took ~10.5 min end to end and completed, so a full run is at the default limit; CI's job itself took 517-531 s of test time plus staging.
  • agentrc's agents/hil-operator.md and skills/hil/SKILL.md say nothing about a background launch timeout (checked 2026-11-10), so the instruction a delegated run follows is this contract's recipe.

Remaining work

Give the recipe's background launch an explicit timeout covering the pool guard plus staging (for example timeout: 7200000 with Bash run_in_background), next to the existing "foreground, Bash timeout 600000" note for wait. Alternative, larger: hil_remote.py detaches the remote run from the local process so a killed launcher does not abort it.

Deferred: separate scope from #4028.

Related: hathach/agentrc#365 — detached HIL daemons ending with the hc terminal; a different launcher-kill path, not the Bash tool timeout.

Dominant language
C
Stars
7.3k
Forks
1.6k
Avg merge
2d 15h
Merged PRs (30d)
88

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from hathach/tinyusb

All issues in hathach/tinyusb

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.