fix: bound POSIX installer lock waits

[jamilahmadzai]

Summary

Fixes #413.

A live but wedged POSIX installer currently leaves every later bootstrap blocked in bare flock 3 forever. Since ensure-monk-agent.sh runs from the plugin startup path, this can make all subsequent coding-agent sessions on the host appear hung.

This change:

• bounds the contended installer-lock wait to 60 seconds by default via flock -w;
• supports MONK_AGENT_INSTALL_LOCK_TIMEOUT as a validated non-negative integer, allowing deterministic tests and operator tuning;
• returns a clear non-zero diagnostic when the deadline expires;
• updates all three rendered POSIX copies (root, Claude/Codex plugin, and Antigravity), avoiding the incomplete-copy problem called out on fix: prevent concurrent launcher race in ensure-monk-agent.sh #50;
• adds an actual kernel-lock regression fixture and exercises it on both Ubuntu and macOS CI;
• verifies both sides of contention: a wedged holder reaches the deadline, while a holder released before it lets installation continue normally.

Verification

The new regression first failed on unmodified v0.1.58: its five-second watchdog had to terminate scripts/ensure-monk-agent.sh. After the patch, all three copies exit on the configured one-second deadline and emit the expected diagnostic. A deterministic release-before-deadline case also proves the installer acquires the released lock and returns the managed binary without using the network.

Locally passed:

./tests/ensure-monk-agent-lock-timeout.sh
ensure-monk-agent lock-timeout tests passed.

./tests/start-monk-agent-fastpath.sh
start-monk-agent fast-path tests passed.

./tests/start-monk-agent-readiness-timeout.sh
readiness_timeout_status=pass elapsed=2s sleeps=2

./tests/start-monk-agent-antigravity-python-path.sh
Antigravity Python fallback handles apostrophes in the config path.

Additional checks:

• sh -n on all changed shell scripts
• git diff --check
• byte-for-byte equality of all three shipped ensure-monk-agent.sh copies

Bounty/product-use context

I installed official plugin v0.1.58 through the Monk Codex marketplace, started monk-agent, authenticated the MCP server with the same GitHub-linked Monk account, initialized this repository as a workspace, and successfully called monk.project.analyze. The linked report is therefore based on a live installed product run, with a deterministic concurrency reproduction—not code reading alone.

[jamilahmadzai]

Independent fork CI is green on the current head 4bef4fd: Install E2E run 33336366543 passed Ubuntu, macOS, and Windows. The installer-lock regression passed on both POSIX runners and now covers both outcomes: a wedged holder exits at the configured deadline, while a holder released before that deadline lets installation continue. The upstream run remains action_required only because fork workflows need maintainer approval.

[jamilahmadzai]

Refreshed this PR against current main, preserving the newly added CI cases alongside the lock-deadline regression. All five local POSIX regression scripts pass, and the three shipped installer copies match. The current-head fork Install E2E run passes on Ubuntu, macOS, and Windows: https://github.com/jamilahmadzai/monk-plugin/actions/runs/34205983157. Ready for review; upstream fork-workflow approval may still be required.

[jamilahmadzai]

Follow-up after checking v0.1.64 and current main: the configurable 60-second lock-deadline implementation is now present byte-for-byte in all three POSIX installer copies, introduced by release commit 3880b41. Thanks for shipping the fix for #413.

There is one test follow-through item: current main Install E2E passes Ubuntu and Windows but fails macOS in the new lock test with flock: command not found. This PR already includes a Python/kernel-lock fixture that does not require a system flock command, checks all three rendered installers, and uses a watchdog plus deterministic release-before-deadline coverage. I reran all five local POSIX regression scripts successfully at the unchanged PR head 1e46130; its previously linked fork CI also passed all three platforms.

Since the production fix has shipped and this repository is generated output, could you port the portable regression fixture into the source generator, confirm how #413/#414 will be credited for the contest, and advise whether you would like this PR closed or retained for the test follow-up? I have left it open rather than duplicating the shipped runtime fix.