test(spec): order the sdui cleanup fd count on the child's own post-exec report

[os-warren]

Fixes #18010

Clause-②: no — the diff is one .test.ts under packages/spec/scripts/, which matches none of the package's files[] entries.

The mechanism, named from the tree

The card's hypothesis was that the count lags the child's exit (an fd inherited by a grandchild, or a lock fd closed asynchronously). Both halves are falsified by the tree, and the real cause is one line earlier:

• The count is not taken after the child exits. It is deliberately taken while the session leader is alive (the comment at the old :98-102), and the failing CI run confirms it: LEADER_ALIVE_AT_COUNT=yes.
• No grandchild can hold the fd. Measured here: a node process holding an inherited non-close-on-exec fd reports PARENT_SELF_LOCKFDS=1, and the child it spawns reports HELPER_LOCKFDS=0. libuv closes it across the spawn, so the helper is not a candidate.

What is left is the only candidate, and it is the one the test synchronises on:

sdui_spawn_detached (scripts/gen-sdui-manifest.sh:88) returns as soon as the pidfile is non-empty (:113-115). Its runner writes that pid on its first line (:96), before the for fd in /proc/$$/fd/* loop that closes the descriptors inherited from the caller (:98-105), and only then execs. So between those two steps the session leader is a bash process that is published as ready and still holds the caller's flock descriptor. That is precisely what Test Core (1/6) counted.

Measured on this tree, 25 runs, timestamps taken with bash's EPOCHREALTIME inside an instrumented copy of the script:

reading	value
window, pid published to descriptors closed	151–297 us (median 174)
margin, descriptors closed minus count taken	10.4–54.3 ms, all 25 negative (the close won)
what buys that margin	sdui_spawn_detached's own sleep 0.05 poll granularity (:117) — not a barrier

So the assertion was ordered on a signal that means "the leader exists", never "the leader let go of my descriptors", and a 0.2 ms critical section was being covered by an unrelated 50 ms sleep. On a six-way sharded runner a single bash process being descheduled for longer than that is ordinary. The assertion was racing something real; it was not wrong about the property.

What changed

The reading is now ordered on the resource, not on the pidfile:

1. Barrier 1 — the spawned command's own post-exec report. The stub counts its own descriptors on the caller's lock and prints them. exec has by then replaced the shell that does the closing, so that line cannot exist until the close has run. The harness waits for the report, never for a value: the stub prints whatever it counts, so a real leak still arrives as a red (proved below).
2. Barrier 2 — the helper has joined the session, so the session-wide count covers both members rather than whoever happened to exist.
3. The session-wide LOCKFDS count is unchanged in meaning and now runs after both barriers, and names its holders (LOCKFD_HOLDERS) so a future red is a process rather than a number.
4. The stub is released by a file instead of a 1200 ms timer, so LEADER_ALIVE_AT_COUNT stops racing node's boot time — the added barriers would otherwise have eaten into that budget.
5. The orphan precondition waits for a member with PPID 1 instead of sleeping a guessed two seconds. A timed-out barrier leaves the field empty, which the existing assertion reads as a red.

Both new barriers are asserted (CHILD_REPORTED, HELPER_IN_SESSION), so a barrier that times out is its own named failure instead of a count taken at some other moment.

⛔ Nothing was skipped, quarantined, loosened to toBeLessThan, retry-wrapped, or given a longer timeout. The vitest timeout is still 120_000.

Ablations — one-time, on the real script, restored and proved byte-identical

Both legs mutate scripts/gen-sdui-manifest.sh in this worktree only, under trap ... EXIT INT TERM, restore with git checkout HEAD -- ..., and verify git hash-object against the HEAD blob.

(1) The lagging state — the OLD assertion fails on it, the NEW one passes. A sleep 0.5 injected between the pid publish and the fd-close loop, i.e. the deschedule made deterministic:

leg	result
NEW test under the lag	exit 0, Tests 1 passed (1)
OLD test (BASE 2882528786 content) under the same lag	exit 1 — LOCKFDS=2, LEADER_ALIVE_AT_COUNT=yes, expected '2' to be '0'

The CI red read '1'; this reads '2' because the injected sleep is itself a session member that inherited the same descriptor — an artefact of the injection, not of the script.

(2) Non-vacuity — the NEW assertion still fails when the thing it pins is deleted. The fd hygiene disabled (if [ -d "/proc/$$/fd" ]; then to if false; then):

ABL_2_EXIT=1
CHILD_REPORTED=yes
CHILD_LOCKFDS=1
HELPER_IN_SESSION=yes
LOCKFDS=1
LOCKFD_HOLDERS=[ 28876(node)]
: expected '1' to be '0'

The holder is the exec'd node leader — the process that can actually survive cleanup, which is what property (2) exists to pin. Both barriers reported yes, so the red is the property, not a barrier artefact.

Restore proof for both legs: RESTORED rel=scripts/gen-sdui-manifest.sh blob=5233551907c06460756c91d061e2078276e42ca1 equal to HEAD:scripts/gen-sdui-manifest.sh, and RESTORE_DIFF_HEAD=[].

Verification

Exit codes captured by redirect-then-$?, never through a pipe.

• Subject test, clean tree: 5 consecutive runs, all exit 0, 1.71–2.91 s (was 4.47 s on BASE — the blind sleep 2 is gone).
• pnpm --filter @objectstack/spec test:repo — exit 0, 31 files / 526 tests. This is the project and the shard that failed.
• pnpm --filter @objectstack/spec test (local project) — exit 0, 482 files / 13771 tests, 1 skipped.
• pnpm --filter @objectstack/spec typecheck — exit 0; check:test-typecheck confirms the test layer compiles under packages/spec/tsconfig.test.json, so this file is in a tsc program.
• Gate family from node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 58 derived, 58 accounted, 0 UNRUN — 53 exit 0, 5 exit 3. The five are check:dts-closure, check:dual-build-cjs-loads, check:lean-entry-closure, check:sourcemap-no-sources-content, check:type-check-debt: all refuse for a missing built dist/ in this worktree. PREREQUISITE NOT MET — not measured, neither a pass nor a failure. They sweep published build output, which this diff cannot reach; CI's Build Core job supplies it.

Verify-lock confounder, ruled out by measurement rather than assertion. This test counts flock descriptors, so a lock-holding wrapper around it is a confounder. Running the probe inside scripts/pm/os-verify-lock.sh: SESSION_VERIFYLOCK_FDS=0 and CALLER_VERIFYLOCK_FDS=0 — the shared lock's descriptor is not in the wrapped tree at all. Lit control on the same grep: a process deliberately holding /tmp/os-heavy-verify.lock reads 1, so those zeros are facts, not a broken probe. The count itself greps the test's own caller.lock basename, which the shared lock's name cannot match; dark control LOCKFDS_DARK=0, lit control CALLER_LOCKFDS_LIT=1.

skip-changeset

Measured, not assumed: npm pack --dry-run --json in packages/spec lists 271 entries, 0 of them under scripts/, and the subject file is not among them. Positive control: README.md, llms.txt and package.json are in that listing, so it is a real reading. Nothing published moves.

Acceptance notes

Out of scope for this PR, noted and not filed:

• sdui_spawn_detached publishes the leader pid before it closes the caller's descriptors, so the pidfile means less than its own doc comment claims ("no inherited descriptors above stderr"). It is not a production defect — the pre-exec shell always proceeds to the close, and nothing in the script reads the leader's descriptors — so the honest fix is the measurement point, not the script. Recorded because the next author to treat that pidfile as a readiness barrier will hit the same thing. Carrier: any future change to sdui_spawn_detached.
• The old orphan scan (for p in $MEMBERS; do [ ... ] && ORPHAN="$p"; done) relies on set -e's &&-list exemption and would abort the harness if a non-orphan member were scanned last. It only ever passed because the session holds exactly one member and that member is the orphan. Rewritten as an if here as part of the barrier change. Carrier: this file.

---

Generated by Claude Code

---

Landing note (seat, 2026-09-17)

Contract review at CONTRACT_REVIEW_TIER on head 65c97a0760: PASS — record is comment 5706854237 on this PR.

⚠️ Correction to this body, appended rather than rewritten. The body attributes this file's tsc coverage to check:test-typecheck under tsconfig.test.json. That program's include stops at src/**/*, so it does not reach packages/spec/scripts/. The file is compiled by check:scripts-typecheck under tsconfig.scripts.json (include: scripts/**/*), which typecheck also runs and which is green on this head. The conclusion holds — the file IS in a tsc program — but the attribution named the wrong one. Corrected here because this repo squashes and the body becomes the permanent commit message on main.

What the review checked that the seat specifically asked it to be sceptical about: whether the reordering makes the assertion deterministic or merely makes the flake rarer. It concluded deterministic by program order, not by timing: the count cannot begin until EXECED=1 is visible, that line is written by node, node exists only after exec at script :104, and the fd-close loop at :96–103 precedes that exec in the same process. A barrier that never arrives reds by name (CHILD_REPORTED=no) — it never passes. All eight original assertions survive with identical matchers; no retry, no loosened matcher, no lengthened sleep, no skip.

Pre-landing checks: ① review PASS on record ✅ · ② check-clause2-carriers --pair 18530 exit 0; ⛔ no carriers were hung on this pair (Clause-②: no, no contract surface) so there is nothing to strip ✅ · ③ re-taken at landing time, latest-run-per-check-name ✅. Governed-surface predicate: 0 of 1 path hits the register ⇒ ordinary queue landing.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1e496f9796126b0398c026c96fb8d240f1982e91 → packageMentionDocs.

[os-litant]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 65c97a07606986f3565a175afad63af12d53ec92

① Derived judgments

• Accept set: unchanged. Three-dot diff origin/main...65c97a07 touches one file, packages/spec/scripts/gen-sdui-manifest-cleanup.test.ts (+98/−18). The same diff restricted to packages/spec/src, json-schema, api-surface, liveness, prompts, spec-changes.json, package.json, CHANGELOG.md and .changeset is empty; the control on packages/spec/scripts returns the one file. No Zod schema, export, JSON schema, error code or ledger moved; 0 files added.
• Public surface: unchanged. @objectstack/spec 17.4.0 files[] has no scripts/ entry and its only glob is src/**/*.zod.ts; tsup entries are ten src/*/index.ts; the build tsconfig excludes **/*.test.ts. The file can reach neither dist nor the tarball.
• What the reordering asserts. Six fields now gate the count: CHILD_REPORTED=yes (the exec'd stub's EXECED=1 line appeared in the runner's stdout, polled up to 30s); CHILD_LOCKFDS=0 (the exec'd leader's own /proc/self/fd holds no link to the lock's realpath); HELPER_IN_SESSION=yes (helper pid in pgrep -s LEADER, up to 10s); LOCKFDS=0 plus LOCKFD_HOLDERS (session-wide count taken after both barriers, holders named by pid and comm); LEADER_ALIVE_AT_COUNT=yes (leader now exits on a release file, not a 1200ms timer); ORPHAN_BEFORE numeric (polled up to 20s for a PPID-1 member instead of sleep 2). All eight original assertions survive with identical matchers (8 → 11); the two 120s timeouts, the skipIf predicate and the survivor/flock-free checks are byte-identical. No retry, no toBeLessThan, no lengthened sleep, no skip.
• Is it deterministic — the mechanism. Old order: pidfile non-empty → count. The runner publishes its pid at script :95, closes inherited fds at :96–103, execs at :104, so the caller could legally observe a pre-exec bash still holding the caller's flock fd; the only margin was the unrelated 50ms poll granularity at :115. New order: count only after EXECED=1 is in the runner's stdout. That line is written by node, which exists only after exec "$@" at :104, which is program-ordered after the close loop at :96–103 in the same process. "Report visible" therefore implies "close loop complete" by program order, not by timing. At that point the session has exactly two possible members — the exec'd leader and a helper forked from it after the close — so any member holding the lock fd means the hygiene failed to close it, which is precisely property (2). A barrier that never arrives reds by name (CHILD_REPORTED=no), it never passes. This is a corrected measurement point, not a window made wider; the flake's mechanism (counting during the pid-publish → close window) is structurally excluded, not made rarer.
• Execution evidence. Not runnable here (no node_modules). On the head, Test Core (1/6) job 104975967974 is success and its @objectstack/spec:test:repo task reports 31 files / 526 tests passed with no skipped count; the file is one of the 31, so the case executed and passed on the very shard that flaked. One green is one datapoint; the determinism claim rests on the program-order argument above. The dev's ablations (old test reds under an injected 0.5s lag, new test reds with the hygiene disabled naming the exec'd node as holder) are unverified, source: PR body.

② Semver level

skip-changeset is right and Clause-②: no is right, from measurement: files[] of the only package touched ships nothing under scripts/; no tsup entry or build tsconfig path reaches the file; the diff adds no .changeset/*.md; the version is untouched at 17.4.0; the Check Changeset check run is success on the head with the label present; os-dev.md:296's criterion (nothing in a package's shipped files[] moved) is met. No path under packages/spec/src/**, no *.zod.ts, no error-code ledger, so neither clause-② limb is hit; Governed Surface Queue Guard is green and packages/spec/scripts/** is not in the governed register. Not re-run by me: npm pack --dry-run (the dev's 271-entry / 0-under-scripts reading is unverified, source: PR body).

③ Boundary flags

1. Open question A/B/C (reorder sdui_spawn_detached so the pidfile is a real fd barrier): answer A, as delivered. Measured consumers of the pidfile on origin/main are the script's own sdui_wait_for_own_server (a liveness/port probe that never reads the leader's descriptors), the collision test (liveness only), and this test — the only consumer that ever counted fds, now ordered on the resource. B would widen the "empty pidfile" window while sdui_stop_detached returns 0 on an empty pidfile (:126), trading a silent reapability hole for a doc-comment nicety; C adds a lifecycle file to a helper whose design note is that silent cleanup failure is the defect. Residual debt: the comment at script :85–86 ("no inherited descriptors above stderr") promises slightly more than the pidfile guarantees. Out of this PR's file surface; needs no card unless a second fd-sensitive consumer appears. Not escalated.
2. Old orphan scan (&&-list under set -e) rewritten as an if at head :183 — verified in the diff, bounded to this file, same gate family. Not a widening.
3. Can the original flake still occur? In this file, no: the count cannot begin before the close loop has completed. Elsewhere, no: the fd-counting spelling (LOCKFDS|caller.lock|/proc/$p/fd) exists in no other test on origin/main. What remains is bounded waits on state (30s/10s/20s) that red by name on a pathologically slow runner, never pass; and the pre-existing PPID-1 orphan predicate, which a subreaper environment would have reddened on the old test identically.
4. PR-body narration error, non-blocking. The body attributes the file's tsc coverage to check:test-typecheck under tsconfig.test.json; that program's include stops at src/**/*. The file is compiled by check:scripts-typecheck under tsconfig.scripts.json (include: scripts/**/*), which typecheck also runs and which is green on the head. The conclusion (the file is in a tsc program) holds; the attribution does not. No code change; a one-line body correction is optional.
5. The "no grandchild can hold the fd" premise (libuv closing across spawn) is unverified by me and immaterial to the verdict: a helper that did inherit the fd would raise LOCKFDS, so the premise can only make the assertion stricter, never greener.
6. Charter hold charter conflict: does a Clause-②: no PR that touches no contract surface still owe an in-seat review before it can land? #18536 (whether a Clause-②: no PR owes an in-seat review at all) is procedural, has no comments and no maintainer ruling; it must escalate to the maintainer and is not answered here. This record is the at-tier review the seat said it was holding for under the stricter reading.
7. Minor, no hole: the HELPER_IN_SESSION case pattern would match an empty $HELPER against trailing whitespace, but HELPER is empty only when CHILD_REPORTED=no, which is asserted first, and a failed spawn yields HELPER=undefined, which cannot match a pid.

Implemented-by: claude/issue-18010-sdui-manifest-lockfd-accounting
Reviewed-by: session_01LvwGppdonww4zGLWZo5rho

VERDICT: PASS

---

Generated by Claude Code