feat(coordination): action acquires per-repo lock for cross-surface mutual exclusion

[marcusrbrown]

The GitHub Action and the Discord gateway will share the same repos. Without
coordination, two surfaces can run against the same repo concurrently, race on
S3 writes, and produce conflicting branches/comments. This wires the Action
into the lock primitives shipped in #547 so that surface mutual exclusion is
enforced at the entry point.

What this does

A new acquire-lock phase runs after dedup. Its outcome drives behavior:

Outcome	Behavior
acquired	Run proceeds; cleanup releases the lock after S3 sync and cache save.
held-by-other	Run skips cleanly (exit 0). Holder ID and surface are logged for operator visibility.
s3-disabled	Object store not configured — coordination is opt-in; run proceeds without a lock.
error	Log and proceed to preserve single-surface behavior. Stale lock recovers via takeover.

The holder ID is action:{run_id}:{run_attempt} so the Discord-side
/fro-bot force-release-lock operator command can identify exactly which
Action holds the lock when manual recovery is needed.

Notes

• Lock release lives in cleanup's finally so it always runs, even on cleanup
  failure. Release errors are non-fatal — the 15-min TTL is the safety net.
• The 15-min TTL with no heartbeat covers the ~2-min median Action run; rare
  long runs recover via stale-takeover on the next acquisition attempt.
• The Action does not run validateProviderSemantics — the gateway, as the
  long-lived process, owns provider validation at startup.
• The lock alone provides cross-surface mutual exclusion. No RunState
  record is created; GitHub already tracks workflow run state.

Test plan

• 8 new test scenarios covering all four outcomes plus stale-takeover race,
  same-surface contention, S3 unavailable, and the defensive no-ETag case.
• Existing cleanup tests updated to pass lockEtag: null (the new option).
• Full suite: 1290 tests pass, 0 lint errors, types clean, build clean.

[fro-bot]

Verdict: PASS

Clean implementation of per-repo coordination locking. The discriminated union on AcquireLockResult guarantees exhaustive outcome handling, the finally-block release in cleanup ensures the lock is always freed, and all error paths are correctly non-fatal. Phase positioning (after dedup, before acknowledge) is the right call — no lock window wasted on deduplicated runs.

Blocking issues

None

Non-blocking concerns

1. Cleanup lock release is untested. All three cleanup tests pass lockEtag: null, so the finally block (lines 202-236 of cleanup.ts) with releaseLock, its success/failure branches, and its catch handler are never exercised. A test with a non-null lockEtag that asserts releaseLock is called (and one where it rejects to confirm non-fatal handling) would close the gap. Low urgency since the logic is straightforward and release failures are tolerated by TTL, but worth adding.

2. Minor heartbeat interval inconsistency. acquire-lock.ts passes heartbeatIntervalMs: 0 (intentional — no heartbeat in v1), while cleanup.ts passes DEFAULT_HEARTBEAT_INTERVAL_MS to releaseLock. The value is likely irrelevant for release, but using 0 in both places would keep the intent consistent and avoid confusion for future readers.

Missing tests

• Cleanup path when lockEtag is non-null (release called, release succeeds)
• Cleanup path when releaseLock returns {success: false} (warning logged, run still succeeds)
• Cleanup path when releaseLock throws (caught, warning logged)

Risk assessment (LOW): likelihood of regression, security exposure, or blast radius

• Regression: Low. The lock is opt-in (S3 must be enabled), and failure modes are non-fatal. Existing single-surface deployments without S3 are unaffected — s3-disabled short-circuits cleanly.
• Security: None. Lock metadata (holderId, surface, runId) is public GitHub Actions data. Conditional S3 writes via ETags prevent lock-stomping.
• Blast radius: Confined to the new phase and the cleanup finally block. No changes to existing phase interfaces beyond the additive lockEtag property on CleanupPhaseOptions.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/agent
Run ID	24940169557
Cache	hit
Session	ses_2399fe6d4ffeDfYAcDJ3QZpDMc