XERK-550: hands-off PR auto-merge + ticket close, opt-in per org

[xerhab]

XERK-550 — PR & ticket close bottleneck

The auto-ticket fleet auto-starts bug tickets, but throughput still stalled on a human reviewing/merging each PR and then manually closing each ticket (closing a ticket is what auto-stops the session and frees the slot). For orgs that opt in, the hub now takes both steps for the class of tickets it already auto-starts.

What changed

Hub (turma/server.js)

• New per-org autoMergeOrgs toggle — the sibling of the existing auto-start switch: file-backed (/data/automerge-orgs.json), on the /api/agents payload + its own SSE, POST /api/jira/<site>/automerge. OFF by default — it merges to the default branch with no human review, so it's a deliberate per-project trust decision, independent of the auto-start switch.
• autoMergeSweep (15s timer, no-op unless opted in) — for a running, idle ticket session that is auto-start-eligible (autoStartContentGate, the same content gate the auto stream uses), queues a mergePr command to the session's host for each PR reading ready === "ready" (green CI + MERGEABLE + no conflict — the flag the agent already computes) and state === "OPEN". Per-PR backoff (autoMergeState); a gh refusal (mergePrResults ok:false — branch protection, review-required, a fresh conflict) marks the PR gaveUp and stops retrying; a silent failure retries to a cap then gives up.
• autoCloseSweep — once every PR a session opened has landed and ≥1 actually MERGED, moves the ticket to Done (the XERK-138 status write-back, routed to a board-cred host of the org) and kills the session, freeing the slot without waiting out the ~10-min Jira poll. The kill is gated on the Done write being queued (never orphans the ticket).
• Eligibility is content-only and reuses autoStartContentGate, so it acts on exactly the class the auto stream would start; a cross-check test pins agreement with autoStartSweep. A Done ticket is excluded (moving to Done is the human's abandon/stop gesture).

Agent (agent/hub-agent.py)

• mergePr command → _merge_pr_async runs gh pr merge --squash --delete-branch <url> (method/branch-delete env-overridable) on a worker thread — off the heartbeat loop (XERK-395), as the manager, not inside a guarded session (the session guard forbids self-merge; the operator's per-org opt-in is the deliberate override). Outcome staged on merge_pr_results, lock-guarded and cleared by identity like spawn_failures. GitHub only for now; a GitLab MR / ADO PR stages a refusal so the hub gives up.

UI (turma/public/org.js) — a second "merge" switch in the header org menu, beside auto-start.

Safety gate — the hub merges only when ALL hold

org opted in · session running, not working, not blocked on a question · PR ready (green CI, mergeable, no conflict) and OPEN · ticket is an actionable, non-held/rejected/duplicate bug in a non-ignored repo, per the org's triage policy · not Done. Sessions run their own QA before opening the PR (repo policy), and green CI is required.

Note: the "bug class" limitation comes from the org's triage policy (excludeTypes) — the same thing that limits auto-start to bugs — not from the ticket type by itself. Enabling auto-merge on an org without a bug-limiting triage policy will auto-merge whatever auto-start would.

How it was verified

• QA: adversarial qa agent (built/drove the real exported sweeps + agent merge_pr) returned FAIL with 3 findings; all fixed and re-verified:
  1. a Done ticket's PR was still merged → excluded statusCategory === "done";
  2. auto-close orphaned the ticket when the Done write couldn't dispatch → kill now gated on the write being queued;
  3. a DRAFT PR was merge-attempted then gaveUp forever → require state === "OPEN".
     A qa-delta re-run confirms the fixes hold.
• Tests: 21 hub cases (XERK-550: / automerge route: in server.test.js) incl. the gate cross-check and the 3 regressions; TestMergePr (10) in test_hub_agent.py; the auto-merge switch in org.test.js. Full turma JS suite (1779) green; agent suite green (bar the known environmental TestDshWeb real-port test). Two suite flakes (control WS ... pongs, drain ...) are pre-existing timing tests that flake on clean origin/main too.

Web ⇄ Android parity

The org-menu auto-merge switch shipped on web only; Android ignores the new autoMergeOrgs payload key (unknown-key-safe) and has no switch yet. Tracked in android/PARITY.md; the hub route works from web regardless.

Docs

.claude/rules/turma-board.md (the two sweeps + gate), .claude/rules/agent-prs.md (the mergePr command), android/PARITY.md.