Plan or claim a batch of issues
next_batchWave dispatch for a fleet: return the top N eligible issues (todo + unclaimed + unblocked WORK — work:false containers are never included), effective-priority ordered, ready to run in PARALLEL (they're mutually independent by construction). Default mode peeks (no claim) so an orchestrator can plan, then claim the ones it fans out; pass claim:true to atomically claim all N now (each comes with a claim_token). LANE-SCOPED by default (your principal's lane + unassigned); pass allLanes:true to include other humans' work. Returns {issues, ready, otherLanes, blocked, claimed} — otherLanes counts ready work stranded in other lanes. When the wave comes back EMPTY and otherLanes>0, the response also carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN and let them answer, rather than reporting an idle queue. Each returned issue carries its own branch (the authoritative rtsc-NN/<slug> every runtime agrees on); with claim:true each also carries its own claim_token. REQUIRED once you claim (claim:true), BEFORE the first edit on any of them: give EACH claimed issue its own git worktree, created from THAT issue's branch — e.g. git worktree add ../<repo>-rtsc-NN -b <branch> origin/main per issue (reuse one that already exists; substitute your repo's default base if it isn't origin/main). Never run two of these issues in the same checkout: a wave is exactly the case this protects, since agents sharing one HEAD/index land their edits on each other's branches. A peek (the default) claims nothing, so it needs no worktree until you claim. Another agent can start in this same checkout at any moment, and isolation cannot be retrofitted once you have edits in flight — a worktree costs a folder and a few seconds; a collision corrupts branches and mislabels work. Only skip if you positively know this environment is single-use and isolated (e.g. an ephemeral per-task container) — and even then a worktree is harmless. A fresh worktree contains only tracked files — no installed dependencies or build artifacts. Before your first build or test in it, run the repo's usual setup (whatever its docs or CI run on a fresh checkout). A wall of errors in files you didn't touch usually means deps are missing, not that the code is broken. Your claim is a LEASE, not a permanent assignment: it expires 30 minutes after you take it behind the retasc mcp-proxy and 2 hours after with no proxy (the response carries the exact claimExpiresAt). Behind the retasc mcp-proxy, ONLY heartbeat and checkpoint renew it — nothing else does, not comments, not status updates, not reading the issue. With NO proxy, if your client echoes the Mcp-Session-Id we hand you at initialize, your own calls renew instead (RTSC-858): every call renews every claim THIS session took, a read as much as a write. Each renewal is a FULL reset to the lease's length from that moment, so one call is enough however little was left. Before any stretch where you will not call Retasc for a while (a long test run, a build, waiting on CI), renew FIRST — prefer checkpoint, which renews AND records the handoff. If the lease lapses, a sweep returns the issue to todo within minutes and another agent can claim it while you are still working on it. WHO RENEWS depends on your client, and only you can tell which case you are in. If you run the retasc mcp-proxy watchdog, it renews the claims IT SAW THIS SESSION MAKE, roughly every 10 minutes by default, for as long as that process is alive — long silent work is then genuinely safe and you need no per-claim heartbeats. Nothing renews a claim the proxy did not see (made in another terminal, over direct HTTP MCP, or by a previous proxy before a restart), and nothing renews once the proxy stops: those run on their bare TTL and are yours to renew. With no watchdog and no session id echoed, every renewal is yours. With no watchdog but a session id, your own calls carry it, right up until your client RECONNECTS, which starts a new session and stops renewal for claims taken under the old one; claim_issue with your claimToken moves them onto the new session and renewal resumes. check_claim settles all of it: renewedByYourCalls says whether this session's calls are renewing that claim right now, and lastRenewedAt moving across a long stretch proves something is renewing you. If this call is refused for billing (BILLING_INACTIVE or MONTHLY_CAP_REACHED), the response carries tellHuman, a ready-to-relay sentence: PASS IT TO YOUR HUMAN. You cannot fix it yourself — only an owner can — so do NOT absorb the refusal and continue with read-only work as if the session were healthy; every value-bearing write will keep failing until they act.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | How many to return (default 5, max 25). | |
| claim | No | Atomically claim all returned issues now (default false = peek). | |
| allLanes | No | Include issues assigned to other humans (default false = only your own lane + unassigned). |