Skip to main content
Glama
Repository Manager

Repository Manager

Run

rm_merge_queue_run

Runs a repository’s serialized merge queue: gates candidate branches differentially against the base, fast-forwards the local base, and optionally pushes and prunes landed worktrees.

Instructions

Run (rm_merge_queue). Serialized merge queue for ANY git repository (CONCEPT:RM-MERGE-QUEUE).

The canonical driver of parallel development: lanes take worktrees, work, then hand branches here, and the queue gates them as merged, fast-forwards the base, and prunes the worktree and branch. Set push false when a scheduler must leave publication to a separate push.

The queue does not know what a gate is. Gates are declared in the target repository's own .mergequeue.yaml — a command, a tier, a timeout, and how to compare its result against the base ref. scion-sdk declares pytest + ruff + its contract scripts; epistemic-graph declares cargo check --all-features + clippy; a docs repo could declare only a link check. A repository with no declaration is REFUSED rather than defaulted, because "declared no gates" and "has no queue configured" must not be the same value.

Gating is differential: only a failure the base ref does not already produce blocks a candidate — the base is legitimately red here, and an absolute gate once deadlocked a queue and stranded 19 branches. A baseline that cannot be produced REFUSES the candidate; it never degrades to allow-all.

run holds that repository's reconciliation-merge LEASE. If another runner holds it the call returns deferred: true with the holder — defer, do not retry in a loop.

landed vs pushed (D-W3WPS-3). Each outcome carries both, separately: landed means the declared base ref fast-forwarded in the LOCAL canonical checkout (proven by re-reading it); when push is true, pushed means that commit also reached the configured remote via the repo's own gated push path (_gate_before_push + push_project — the same pre-commit gates and GH013/divergent-remote handling a manual push gets). With push false, publication is deliberately deferred to a separate push. A push failure never fails the landing — landed: true, pushed: false is a legitimate, visible intermediate state; check push_error on the outcome for why. The queue's own run summary also reports pushed/landed_unpushed counts.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "rm_merge_queue_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
baseNoBranch to land onto. Defaults to the repo's declared base.
pushNoPublish a landed base through the repository's gated push path. Set false for the fast queue timer; publication is then a separate, explicit push.
pruneNoRemove each landed candidate's worktree and branch through the guarded prune (merge-base re-checked at delete time, a refs/lane-backup anchor written first, `git branch -d` never -D, and a worktree holding uncommitted work is refused).
branchNoCandidate branch for enqueue/withdraw. Defaults to that tree's HEAD.
reasonNoWhy a candidate is being withdrawn.
repo_pathNoAny working tree of the target repository. This is what makes the queue cross-project: one server, N repositories, each with its own lease, candidate store, and gates. Defaults to the server's cwd.
batch_sizeNoCandidates gated together per run (0 = the repo's declared batch_size).

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.5.7
    • changedInput schema / properties / push / description
      Previous value: -"Publish a landed base through the repository's gated push path. Set false for the fast queue timer; the phased-push scheduler then owns publication."New value: +"Publish a landed base through the repository's gated push path. Set false for the fast queue timer; publication is then a separate, explicit push."
  2. First observedv3.5.1

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavior far beyond the annotations: lease contention returns deferred:true with the holder, a repository with no gate declaration is REFUSED, gating is differential against the base ref, and landing vs push are separate outcomes with push_error surfaced. The prune parameter's guards (merge-base re-check, backup anchor, branch -d, uncommitted-work refusal) are consistent with destructiveHint:false rather than contradicting it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and information-rich for a genuinely complex tool, with the push and landed-vs-pushed rules front-loaded in bold. Some material — the catalogue of what gates other repositories declare — is illustrative rather than actionable and lengthens the definition, and the opening "Run (rm_merge_queue)" is redundant with the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything needed to call this correctly: lease deferral handling, refusal on undeclared gates, push semantics and the legitimate landed:true/pushed:false state, and pruning guards. An output schema exists, so the description's explanation of outcome fields is supporting context rather than a gap-filler.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; the description adds real semantic weight on top by explaining the consequence of push=true/false and the landed/pushed split that follows. It adds little beyond the schema for base, batch_size, branch, and reason, which the schema already documents well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — running the serialized merge queue — and immediately spells out the concrete actions: gates candidates as merged, fast-forwards the base, prunes the worktree and branch. The workflow framing (lanes hand branches here) makes it clearly distinct from the enqueue/status/withdraw/config siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit operational guidance for the key parameter ("Set push false when a scheduler must leave publication to a separate push") and an important anti-pattern ("defer, do not retry in a loop"). It does not explicitly route against siblings like rm_merge_queue_enqueue or rm_merge_queue_status, relying instead on the workflow narrative to imply ordering.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools