gotchas: add 568 - awscrt appexit TIMEOUT flake on cp314t

A subprocess-exit self-test's own hardcoded wall-clock TIMEOUT can fail
only on cp314t, only on one version, with no code change behind it -
free-threading's extra per-object overhead tips an existing margin rather
than creating a new bug (the awscrt 0.37.0 test_appexit case investigated
on PR #2278).

Author: luhenry

skills/python-project-porting/references/gotchas-index.md

@@ -452,6 +452,11 @@ The porting gotchas (548 of them) live in [`references/gotchas/`](gotchas/), spl
   cache-populating step on `ubuntu-latest` and hand the tarball to the riscv job, and patch the
   extracted sdist rather than the checkout when a target sits inside a submodule
   (the couchbase case).
+- **569** — A tag can check out clean and still hand a build literal Git LFS pointer stubs
+  instead of real content, when upstream squash-merges former git submodules into the main
+  tree without resolving their LFS objects first — verify by sha256 against the pointer's own
+  `oid` before trusting a same-content fetch from the pre-merge submodule (the semgrep
+  v1.177.0 case).
 
 ### cibuildwheel mechanics, the matrix & abi3 — [`gotchas/cibuildwheel-matrix-and-abi3.md`](gotchas/cibuildwheel-matrix-and-abi3.md)
 
@@ -1177,6 +1182,11 @@ The porting gotchas (548 of them) live in [`references/gotchas/`](gotchas/), spl
   and unresolved without riscv64 hardware to debug interactively — not scenario-specific to
   whichever test happened to be running, and distinct from an already-open pgsql-hackers
   riscv64/GCC memory-failures thread (that one is sporadic; this one is deterministic).
+- **568** — A subprocess-exit self-test's hardcoded `TIMEOUT` failing only on `cp314t` for
+  one version, with byte-identical test source and no relevant code change across versions,
+  is free-threading's per-object overhead tipping an existing margin on a shared riscv64
+  runner (awscrt 0.37.0's `test_appexit`) — patch the timeout with headroom, don't skip the
+  test that proves the extension doesn't crash the interpreter on exit.
 
 ### Licensing & GPL sources — [`gotchas/licensing-and-gpl.md`](gotchas/licensing-and-gpl.md)
 

skills/python-project-porting/references/gotchas/test-failures-and-flakes.md

@@ -64,6 +64,10 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
   path is real but unresolved on riscv64 without hardware to reproduce interactively —
   confirmed not threading-specific (it crashes both the single- and multi-threaded variant
   of the same helper), diagnosis stops there honestly.
+- **568** — A subprocess-exit self-test's own hardcoded `TIMEOUT` failing only on `cp314t`,
+  only on one version, with byte-identical test source across versions, is free-threading
+  tipping an existing margin, not a new bug — patch the timeout with real headroom rather
+  than skip the test.
 
 ---
 
@@ -1318,3 +1322,46 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
     the built `initdb` (gotcha 115's technique) to see whether the fault is in `initdb.c`
     itself or in something it links against; try a newer PostgreSQL point release; try an
     older/newer GCC than 14.3.1 in the manylinux image.
+
+568. **A subprocess-exit self-test with its own hardcoded wall-clock `TIMEOUT` can fail only
+    on `cp314t`, only on one version, with no code change behind it — free-threading's extra
+    per-object overhead tips an existing margin, it doesn't create a new bug (the awscrt
+    0.37.0 `test_appexit` case).** awscrt's `test_appexit.TestAppExit.test_http` runs
+    `test/appexit_http.py` as a subprocess once per teardown stage and asserts each exits 0;
+    every wait in that script (HTTP connect, body callback, connection-shutdown future, both
+    `ClientBootstrap`/`EventLoopGroup` `shutdown_event.wait()` calls) shares one hardcoded
+    `TIMEOUT = 30.0`. On this repo's riscv64 runners, only the `cp314-cp314t` leg of 0.37.0
+    failed, at the `ClientBootstrapDone` stage, with `AssertionError: 0 != 1` from
+    `subprocess.Popen(...).returncode` — while the same leg of the immediately preceding
+    0.36.3/0.36.4 (built in the very same PR run) and the 0.37.0 cp311/cp313 legs all passed.
+    - **Rule out a version-specific regression before treating a fixed-timeout failure as a
+      real bug**: `git diff <old-tag> <new-tag> -- test/appexit_http.py test/test_appexit.py`
+      found *zero* diff across three released versions, and the only source changes at all
+      were trivial submodule bumps (`aws-c-common`, `aws-c-s3`, `aws-lc`) that don't touch
+      `aws-c-io`'s bootstrap/event-loop/host-resolver shutdown path. Byte-identical test
+      files plus an unchanged code path rules out "new test hit a new bug" and "this
+      version broke something" — the margin already existed.
+    - **Distinguish a hang from a timing margin by reading what the background threads were
+      doing when the timeout fired, not just that it fired.** The subprocess's own
+      `awscrt.io.init_logging(Trace, 'stdout')` output shares the same fd the test harness
+      captures, so on this repo's shared runners a concurrent native thread's writes land
+      byte-interleaved with the Python traceback (literally splitting one log line, e.g.
+      `...cache due to shutdown` becoming `...caTraceback...` then resuming
+      `...he due to shutdown`). Reading past the corruption showed the DNS resolver's own
+      maintenance loop re-resolving the request host roughly once a second for ~24 of the
+      30-second budget before it decided to kill its background thread, and only then did
+      the channel-bootstrap-release / event-loop-destroy sequence that fires
+      `shutdown_event` begin — all of it clean, no error, just late. That is a margin
+      problem (under 6s left for the rest of native teardown to reach Python), not a
+      deadlock.
+    - **Fix scope: patch the hardcoded timeout with `Upstream-Status: Inappropriate` and
+      real headroom, don't skip the test** — this is gotcha 316's "artificial test
+      limitation, not a real defect" case again, and patching-and-licensing.md lists a fixed
+      timeout as an explicitly justified patch reason. Skipping `test_appexit` outright would
+      have cost the one test in the suite that actually proves the package's native
+      extension doesn't crash the interpreter on process exit — the exact thing worth
+      shipping a wheel to verify. Tripling `TIMEOUT` (30s → 90s) keeps that coverage while
+      giving a busy shared riscv64 runner driving a free-threaded (no-GIL) interpreter —
+      whose per-object atomic refcounting adds measurable overhead to native-callback-into-
+      Python teardown chains like this one — comfortable room, and it still fails well
+      inside the job's own timeout if the shutdown genuinely never completes.