[thymikee]

Summary

pnpm gate unit-ci (and other whole-repo gates) did not take the host validation lock. Four worktrees ran it at once on a 12-core Mac; load reached ~1000 and every run hit false 5 s test timeouts.

pnpm gate <id> now runs heavy gates under the same lock that check:affected --run and check hold: same owner, waiter output, dead-owner reclaim, and 2-hour timeout. No second lock.

• Locked (heavyGate in CHECK_CATALOG, hostLocked): unit, unit-ci, provider-integration (whole-repo suites), fuzz-parsers, mutation, mutation-affected, concurrency-torture (many workers/processes). Cheap gates stay unlocked.
• Re-entry: a gate run inside a locked validation sees the inherited AGENT_DEVICE_VALIDATION_PARENT and runs directly, so nothing deadlocks.
• CI: GITHUB_ACTIONS=true runs the gate unlocked (single-tenant runners). Unsupported hosts (Windows) also run unlocked.
• acquireValidationLock takes an optional env, so nested-owner detection reads the same environment as the gate runner.
• Docs: AGENTS.md and docs/agents/testing.md name the locked gates. To stay inside the guidance byte budgets, I removed a few duplicate sentences in testing.md/pull-requests.md.

The lock protocol (publish, activate, finish) and the signal-to-exit-code mapping have one owner in scripts/check-affected: runLockedCommand and abortOnTerminationSignal. Validation runs and gates both use them.

No linked issue.

Validation

• Tested SHA: 1628711.
• pnpm check:affected --run --head 1628711576 exits 0 with exactCommit: true (all runnable checks passed, including lint on the merged origin/main).
• scripts/gate/host-locked.test.ts (7 tests) and host-lock.test.ts (4 tests) pass. They cover waiting, the exit code, nested no-deadlock, unlocked cheap and GitHub gates, a signal while waiting (143), a signal while the locked command runs (143, command group gone, lock and active.json removed), and runLockedCommand publishing and clearing ownership.
• pnpm gate unit-ci waited behind another owner, then ran through the shared runLockedCommand path: exit 0, 16977 tests passed, lock released.
• CI owns full coverage, integration, and native lanes.

🤖 Generated with Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.53 MB	5.53 MB	0 B
Package (unpacked)	5.53 MB	5.53 MB	0 B
Package (download)	1.68 MB	1.68 MB	-2 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	42.2 ms	41.9 ms	-0.3 ms
CLI --help	86.1 ms	88.8 ms	+2.7 ms

[thymikee]

The locked branch of executeGate copies the lock-activation protocol from executeValidationCommand almost line for line (https://github.com/callstack/agent-device/blob/cdc78ec/scripts/gate/host-locked.ts#L62), plus the SIGHUP/SIGINT/SIGTERM to 129/130/143 mapping from openValidationRun. Orphan reclaim in readOrphanCommand depends on one exact order: publish ownership, then activate, then finishCommand in finally. Two copies of that protocol can drift apart. If one changes the handshake, the kill grace or the active.json contents, the gate path can leave orphans that cannot be reclaimed, or start a check before ownership is published. The rule should be that every command run under the host validation lock goes through one function in scripts/check-affected that owns publish-then-activate-then-finish. Please extract runLockedCommand(lock, receipt, command, { cwd, env, signal, onStdoutChunk, onStderrChunk }) from executeValidationCommand, keep its log, heartbeat and receipt bookkeeping around it, and have executeGate call it. Move the signal-to-exit-code mapping into one shared helper that openValidationRun and executeGate both use.

Not blocking, and you can take or leave these: docs/agents/testing.md now drops unrelated rules to fit the byte budget (no lock wrappers or lock-file deletion, never call a failing gate passed, read required-check status on the PR, initial/final checks do not sandbox the checkout, and the authorized incomplete draft line in pull-requests.md), so shortening the new sentences or rewording the existing "Both broad commands acquire the same host lock" line would keep them; and cleanEnv in scripts/gate/host-locked.test.ts spreads extra twice, where only the second spread has any effect.

Would it be simpler to keep the hostLocked trait and requiresHostLock, replace the roughly 50-line locked branch with a call to the extracted runLockedCommand and signal helper, and let host-locked.ts shrink to the predicate, acquire, run and release? The lock protocol would then have one owner, and no ADR is needed.

This review covers cdc78ec. I read the change but did not run the new tests or your locked pnpm gate unit-ci run. No test covers a signal that arrives while the locked command is running, as opposed to while waiting. The Lint, Typecheck & Package failure is in oxlint on packages/platform-apple/src/snapshot-route.test.ts:1003, the 1000-line cap tracked in #3890 on main. It is likely unrelated, since this PR only touches scripts/ and docs/. There are no conflicts. Before merge, the locked run needs to go through the shared helpers, and CI lint stays red until #3890 lands.

[thymikee]

Addressed in 1628711 (also merged origin/main, which carries the snapshot-route line-cap fix).

Blocking: one owner for the lock protocol

• runLockedCommand(lock, receipt, command, { cwd, env, signal, onStdoutChunk, onStderrChunk }) now lives in scripts/check-affected/host-lock.ts. It owns publish → activate (stdin: 'run\n') → finishCommand in finally, plus the detached/kill grace/AGENT_DEVICE_VALIDATION_PARENT env.
• executeValidationCommand keeps its log, heartbeat and receipt bookkeeping around it. finishCommand now runs inside the helper, before the report collection.
• Signal mapping moved into abortOnTerminationSignal(controller) (scripts/check-affected/termination.ts), used by openValidationRun and executeGate.
• host-locked.ts keeps the hostLocked trait and requiresHostLock, and shrinks to predicate / acquire / run / release.
• New tests: a signal while the locked command runs (host-locked.test.ts: command stopped, exit 143, lock and active.json gone). A direct runLockedCommand test checks that ownership is published with the receipt and pid while it runs and cleared after (host-lock.test.ts).

Non-blocking

• docs/agents/testing.md: the lock-wrapper / lock-file rule, "never call a failing gate passed", required-check status, and the initial/final checks line are restored. The new text is a single reworded line: "Both broad commands and heavy pnpm gate ids acquire the same host lock." pull-requests.md regains the authorized incomplete draft line. AGENTS.md keeps its original lock sentence, and its parallel-worker bullet now reads "...and heavy pnpm gate ids share one lock."
• cleanEnv no longer spreads extra twice.

[thymikee]

This PR is ready at 1628711. The findings from the earlier review at cdc78ec (#3900 (comment)) are fixed, and I found nothing new in the code. I read the new host-lock and gate tests but did not run them locally. CI shows 18 checks with none failing at this head. There are no conflicts. Not blocking, and you can take or leave it: the PR body Validation section still cites cdc78ec, 8 files, 6 tests and removed sentences in testing.md and pull-requests.md, which the later commits reverted. It would help to update it to 1628711, 11 files, 7 gate tests plus the runLockedCommand test, and to re-run pnpm gate unit-ci through the extracted helper if you cite a locked run, since the cited run predates runLockedCommand. Nothing else must happen before merge.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-22 09:46 UTC