Skip to content

feat: park Bitbucket Cloud ship lanes while awaiting review - #20

Merged
andrew-codes merged 6 commits into
mainfrom
fm/fm-bb-park-review
Nov 16, 2026
Merged

andrew-codes merged 6 commits into
mainfrom
fm/fm-bb-park-review

Conversation

@andrew-codes

@andrew-codes andrew-codes commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Intent

Close the Bitbucket Cloud gap tracked in #17, which the upstream sync (PR #16) surfaced. Issue content:

  • Upstream feature: a9ae3c0c feat(crew): park ship lanes while awaiting review (feat(crew): park ship lanes while awaiting review kunchenguid/firstmate#7965). New bin/fm-park.sh parks a ship lane from a verified clean state once its PR only awaits human review, relaunches a fresh worker on review activity, and cleans the lane up on merge.
  • What the fork's Bitbucket support lacks: fm_park refuses any PR that is not GitHub or GitLab (parking supports GitHub pull requests and GitLab merge requests only). A Bitbucket Cloud lane can never be parked, so it holds a worker slot for the whole review wait. The gate reads a forge snapshot with only a GitHub normalizer (GraphQL) and a GitLab normalizer (glab api); there is no Bitbucket normalizer. The snapshot must provide: no merge conflict and not behind base, mergeability computed, CI green on the current head, no changes requested, zero unresolved review threads (all read), and a reviewer-bot quiet window.
  • What a Bitbucket version needs: a bitbucket branch in the snapshot function that reads the PR through twg bb pull-requests get/mergeability/... the way bin/fm-pr-health.sh already does (conflict, failed merge check, failed build, unresolved review threads), and a Bitbucket normalizer producing the same snapshot shape. Review-trigger relaunch (new comment, changes requested) and merge detection should reuse the existing Bitbucket merge poll and the fork's review-thread observer. Requested-changes and reviewer-bot detection need a decision on what Bitbucket exposes (reviewer approval state; bot accounts), and the bounded read time FM_PARK_READ_SECS must still hold given twg latency.
  • Files involved: bin/fm-park.sh (provider check near the parking supports GitHub ... refusal, GITHUB_QUERY/GITHUB_NORMALIZE/GITLAB_NORMALIZE, snapshot, gate evaluation), bin/fm-pr-health.sh (existing Bitbucket reads to reuse), bin/fm-pr-lib.sh (shared PR helpers), tests/fm-park.test.sh (add a Bitbucket case with a stubbed twg), docs/configuration.md (park-on-review section), docs/fork-configuration.md and FORK.md (user-facing note when it ships).

Found during the upstream sync in #16 (upstream range 913bb7a..427056c).

What Changed

  • bin/fm-park.sh no longer refuses Bitbucket Cloud pull requests. It adds a Bitbucket snapshot branch that reads the PR through twg (two reads run together under the single FM_PARK_READ_SECS limit) and a normalizer that produces the same snapshot shape as GitHub and GitLab. It covers conflict, failed merge check, build state on the current head, changes requested, unresolved review threads, and review-bot handling. A read that runs over the limit counts as unreadable, so the lane is not parked.
  • bin/fm-t3-mcp.mjs: waitRun now starts with its first wait slice capped at the total timeout, then recomputes the slice from the remaining deadline after each timed-out wait.
  • Added Bitbucket cases to tests/fm-park.test.sh using a stubbed twg. Documented Bitbucket parking in docs/configuration.md, docs/fork-configuration.md (settings, parking conditions, examples) and FORK.md.

🤖 Generated with Claude Code

Risk Assessment

⚠️ Medium: The Bitbucket normalizer, gate, trigger and bounded parallel reads implement the intent coherently and no concrete wrong-result path was found, but it is a large new shell/jq forge integration whose Bitbucket API field assumptions (participants state, comment_count, inline anchoring) were not checked against a live twg, and it carries two unrelated edits.

Testing

I ran the real fm-park.sh test suite, which drives the actual script against a stubbed twg. The Bitbucket cases cover the gate, relaunch triggers and the FM_PARK_READ_SECS bound. All 37 tests passed. I did not run a live Bitbucket or Herdr lab session, so real twg latency and real Bitbucket data were not exercised.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Bitbucket gate (stubbed twg): clean PR parks; draft, declined, conflict, behind, uncomputed mergeability, failing or missing build, changes requested, unresolved threads and unfinished review bot each… ✅ pass live fm-park-test.txt: 'ok - bitbucket gate: ...'
Bitbucket parked PR relaunch triggers: new head, failing build, requested changes, conflict, unresolved thread or new comment relaunch a worker; approvals, outages and merges do not ✅ pass live fm-park-test.txt: 'ok - a clean Bitbucket PR parks with its abbreviated head ...'
A hung twg read is cut at FM_PARK_READ_SECS and the gate reports an unreadable forge ✅ pass live fm-park-test.txt: 'ok - a hung twg read is cut at FM_PARK_READ_SECS ...'
Evidence: fm-park test transcript

Source: fm-park test transcript

1..37
ok - github gate: clean PR parks, and draft, closed, conflict, behind, unknown mergeability, CI pending/failing/absent, changes requested, unresolved and unread threads each refuse
ok - github gate refuses while a required check of the base branch has not reported on the head, or the requirement cannot be read
ok - github gate waits for every reviewer bot to submit a review of the current head, or the quiet window since it was pushed
ok - gitlab gate: clean MR parks, and draft, conflict, rebase, CI running/failed/absent, changes requested, other merge blockers, unresolved threads, a pipeline on an older commit, and a review bot that has not finished each refuse, across every page of discussions; a failed page is unreadable for gate and tick
ok - bitbucket gate: clean PR parks, and draft, declined, conflict, behind, uncomputed mergeability, other blocking merge checks, CI running/failed/absent or a missing required build, changes requested, unresolved or unread threads, and a review bot that has not finished each refuse; approvals and the author's own notes do not; an unreadable half or head is never clean
ok - a clean Bitbucket PR parks with its abbreviated head, and a new head, failing build, requested changes, conflict, unresolved or unread thread, or new comment relaunches a fresh worker; approvals, outages and merges never do, and a declined PR is reported once
ok - a hung twg read is cut at FM_PARK_READ_SECS, both Bitbucket reads share that one bound, and the gate reports an unreadable forge
ok - park evaluates the gate twice, leases the slot, writes a private record, stops the agent once, and declares the wait
ok - park refuses an unsupported backend before leasing, recording, or stopping
ok - a head change between the verdict and the stop refuses the park and leaves the agent running
ok - an instruction or a new turn arriving after the preflight refuses the park before the agent is stopped
ok - park holds the inbox delivery lock across its final check and stop, refusing a newly delivered instruction without stopping the agent
ok - park leaves the task metadata lock available to fm-control exit
ok - a pending park stays watched during stop, promotes a later stop, and expires only after the stop bound
ok - a hung agent check on a pending park ends within the tick, and the next tick resumes and settles it
ok - a park whose record cannot be written refuses before the agent is stopped
ok - park refuses a busy or unfinished worker, a waiting instruction, a dirty or lagging copy, an unarmed merge poll, an unleasable slot, and a failed stop
ok - a lane re-parked after a relaunch keeps its own durable lease, and a slot leased to another holder refuses the park
ok - head change, failing checks, changes requested, an unresolved thread, a conflict, and new or edited GitHub or GitLab comments, including an inline reply in a resolved thread, each relaunch a fresh worker with the trigger in its instructions
ok - an edited comment older than the latest 100 is detected and relaunches the parked lane
ok - a parked branch that merely fell behind its base stays parked
ok - a relaunch slower than the whole tick budget completes once, is never killed, and is reported by the next tick
ok - a tick that runs out of time resumes at the next unvisited lane, so a slow early lane cannot starve later ones
ok - an unchanged parked PR and a bare approval stay parked silently
ok - a failed relaunch keeps the park record, reports once, and waits for a manual resume
ok - closed-without-merge reporting for unparked lanes requires a feature flag and does not require an idle worker
ok - tick parks nothing without opt-in, reads nothing when opted out of cleanup too, never parks an unclean lane, and parks a clean idle one under config/park-on-review
ok - merge-time cleanup requires opt-in for unparked lanes and always cleans parked lanes
ok - land queue fails when the cleanup request cannot be written
ok - a lost pool slot and its leftover paths survive in the detached land report
ok - a detached merge-time cleanup returns at once, runs its slow teardown to completion, and the next tick reports it once
ok - a pending merged-lane cleanup survives watcher restart and reports its outcome once
ok - a temporary control-lock refusal stays pending and retries to one reported cleanup outcome
ok - a cleanup killed during its teardown keeps its request, and the next tick retries it and reports once
ok - a cleanup request for a PR the lane no longer names is dropped without a teardown or a report
ok - an action report survives until the tick has recorded its wake, then is reported once
ok - a merge-time cleanup waits for a relaunch of the same lane that is under way
FM_TEST_COMPLETE

Pipeline

Updates from git push no-mistakes

Run outcome: ✅ pipeline passed on 85c4feaf.

✅ **Intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 warning
  • ⚠️ bin/fm-t3-mcp.mjs:1000 - Two changes in this branch are not needed by the Bitbucket parking intent. (1) bin/fm-t3-mcp.mjs waitRun slice arithmetic is a T3 wait-budget change with no link to Bitbucket parking. (2) bin/fm-park.sh action_start gets an extra 2>/dev/null on the subshell to hide setpgid warnings. Neither serves the issue Bitbucket: support parking ship lanes while awaiting review #17 requirements (Bitbucket snapshot/normalizer, review-trigger and merge reuse, bounded read time). Smallest honest remedy is to move them to their own change; confirm whether they are intended to ship here.
✅ **Test** - passed

✅ No issues found.

  • Live validation: ✅ go - 3 of 3 scenarios driven live against the product
Scenario Result Live Evidence
Bitbucket gate (stubbed twg): clean PR parks; draft, declined, conflict, behind, uncomputed mergeability, failing or missing build, changes requested, unresolved threads and unfinished review bot each… ✅ pass live fm-park-test.txt: 'ok - bitbucket gate: ...'
Bitbucket parked PR relaunch triggers: new head, failing build, requested changes, conflict, unresolved thread or new comment relaunch a worker; approvals, outages and merges do not ✅ pass live fm-park-test.txt: 'ok - a clean Bitbucket PR parks with its abbreviated head ...'
A hung twg read is cut at FM_PARK_READ_SECS and the gate reports an unreadable forge ✅ pass live fm-park-test.txt: 'ok - a hung twg read is cut at FM_PARK_READ_SECS ...'
  • bash tests/fm-park.test.sh (37 tests, exit 0, no not ok)
✅ **Document** - passed

✅ No issues found.

⏭️ **Lint** - skipped
  • ⚠️ linter found issues (exit code 1)
✅ **Push** - passed

✅ No issues found.

Also in this PR

  • bin/fm-t3-mcp.mjs: the waitRun slice arithmetic now keeps the T3 wait budget exact on the first slice. This is the pipeline's CI-round fix for a flaky timing test, kept here because flakiness is fixed even when unrelated.
  • bin/fm-park.sh: action_start silences its subshell's stderr so a bash setpgid warning under load does not leak into the watcher output. It sits in the file this change owns.

Closes #17

@andrew-codes andrew-codes changed the title feat(park): park Bitbucket Cloud pull requests while they await review feat: park Bitbucket Cloud ship lanes while awaiting review Nov 16, 2026
@andrew-codes
andrew-codes merged commit 2e789e1 into main Nov 16, 2026
65 of 69 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bitbucket: support parking ship lanes while awaiting review

1 participant