docs: pair the hint_exit examples with a task timeout that outlives their wait

[codeAnqiang-ma]

Fixes #5

The problem

docs/checks.md labels this "the canonical shape" for a check with a fallback hint, and promises right after it that "the hint stays visible in the task box until replaced":

check: |
  wait_cwd --timeout 60 "/tmp/gym/$DIRNAME" || \
    hint_exit "Still waiting... check where your shell is with pwd."

With default settings that hint can never appear. The snippet has no timeout:, so the attempt uses the 30 s default (internal/engine/engine.go:42-45, :548-551), and on expiry the runner SIGKILLs the whole process group (internal/engine/runner.go:135-140) while wait_cwd is still 30 s away from returning. The || hint_exit arm is never reached, and the attempt is recorded as exit 124 rather than HintExitCode (42), so the engine takes the ordinary-failure path (:570-575) and just restarts the check. The task still completes normally once the condition holds — only the hint is silently dead.

Three examples had a --timeout at or above the default with no override: docs/checks.md (wait_cwd --timeout 60, wait_file_mode --timeout 50) and docs/authoring-guide.md (wait_port --timeout 60).

What this changes

Docs only, 15 insertions across 2 files:

1. The three examples get the companion timeout: they need. For the wait_file_mode one that means restoring timeout: 60 — the snippet was excerpted from paths/sample-linux-101/030.files-and-folders/060.lock-it-down/unit.md, which already sets it and explains why in a comment ("the attempt timeout must exceed that or the hint never fires"). The other two get timeout: 70 for their 60 s waits, keeping the same ~10 s headroom that unit uses.
2. The constraint is stated where the two flags are defined — the --timeout bullet in docs/checks.md and the timeout bullet in docs/authoring-guide.md — so an author who wants a long bounded wait knows to raise the attempt timeout instead of rediscovering this the hard way.

I deliberately kept the examples' original wait durations. Lowering them to --timeout 15 (the value used in every other example in the repo) would fix the snippets just as well with an even smaller diff — happy to switch if you prefer that direction.

Testing

Ran on Linux (golang:1.24, --cap-add=NET_ADMIN so the netlink-backed tests execute for real), on this branch:

$ make build
CGO_ENABLED=0 go build -o bin/shellgym ./cmd/shellgym

$ ./bin/shellgym validate --path paths/sample-linux-101
OK: 8 modules, 27 units

$ go test ./...
?   	github.com/iximiuz/labs-content/tools/shellgym/cmd/shellgym	[no test files]
ok  	github.com/iximiuz/labs-content/tools/shellgym/internal/bus	0.048s
ok  	github.com/iximiuz/labs-content/tools/shellgym/internal/checkclient	0.053s
ok  	github.com/iximiuz/labs-content/tools/shellgym/internal/content	1.450s
ok  	github.com/iximiuz/labs-content/tools/shellgym/internal/engine	38.114s
ok  	github.com/iximiuz/labs-content/tools/shellgym/internal/state	0.065s
?   	github.com/iximiuz/labs-content/tools/shellgym/skills	[no test files]
?   	github.com/iximiuz/labs-content/tools/shellgym/ui/tui	[no test files]
ok  	github.com/iximiuz/labs-content/tools/shellgym/ui/webui	0.305s

No test is added, since nothing but prose and YAML snippets changed. The behaviour itself is verified in #5 with a throwaway internal/engine test that runs the old snippet verbatim under production defaults (no hint within 40 s; attempt 0: exit=124 timedOut=true dur=30.1s) alongside a control that only raises timeout: and does receive the hint. I left that test out of this PR on purpose — it takes ~60 s of wall clock and asserts a documented invariant rather than product behaviour. As mentioned in the issue, a shellgym validate warning for --timeout N with N >= the effective attempt timeout would be the place to catch this mechanically; glad to look at that separately if you want it.

Note: on macOS internal/checkclient does not compile (syscall.Stat_t.Mode is uint16 on Darwin, uint32 on Linux, at checkclient.go:369), unrelated to this change — hence the Linux container for the test run.

Licensing

Per CONTRIBUTING.md: I license this contribution to Ivan Velichko (iximiuz Labs) under any terms, including commercial licensing and relicensing of Shell Gym as a whole.

---

Produced with AI assistance; I reproduced the behaviour locally and reviewed every line of this change myself.