feat(mcp): deliver a completed loop iteration as a customer results payload

[luciferlive112116]

Summary

Implements #4801 — once a loop iteration completes, package its result for the customer instead of leaving it unassembled. This closes the Rent-a-Loop path's delivery end (#4778), mirroring the intake bridge (#4798) at the other end.

• new buildResultsPayload(result) in packages/loopover-engine/src/results-payload.ts (pure): formats a completed iteration's already-computed metadata into a PR link, a plain-language one-sentence summary, and a bounded diff preview (capped at MAX_DIFF_PREVIEW_FILES; totals still count every file). No IO, no GitHub calls — it formats the result, it does not fetch, open, or deliver anything. Handles the no-PR-opened case (null link + honest summary) and defaults missing per-file line counts / status.
• new loopover_build_results_payload MCP tool (src/mcp/server.ts) exposing it; src/results-payload.ts is a thin re-export shim over the engine module.

Acceptance (#4801): a completed iteration produces a correct, readable result payload without manual assembly — tested at the engine level and end-to-end through the MCP tool.

Closes #4801

Scope

• Conventional Commit title (feat(mcp): …).
• Focused: the results-delivery composer + its tool, on the merged intake/claim-plan chain.
• Follows CONTRIBUTING.md; no site//CNAME/VitePress.
• Linked open issue: Closes #4801.

Validation

• git diff --check
• npm run typecheck clean; npm --workspace @loopover/engine run build + npm run build:mcp clean
• npm run test:coverage on the changed code: results-payload.ts 100% lines & branches (18/18); the new src/mcp/server.ts handler + schema + registration are fully covered (every changed line, both branch sides — verified against the diff).
• MCP tool-invariant suites pass with the new tool (mcp-output-schemas "outputSchema on EVERY tool" + "schema-valid structured content").
• Tests cover completed-PR, no-PR (null & omitted), omitted-changes, zero line-counts, singular/plural, and the preview-cap — engine + end-to-end through the tool.

If any required check was skipped, explain why:

• Full test:ci not run end-to-end locally (Linux-only shell/self-host steps on Windows); the change-relevant gates above were validated directly.

Safety

• No secrets, wallet/hotkey/coldkey, trust scores, rewards, private rankings, or private maintainer evidence — the payload is a public-safe PR link + summary + diff-stat, source-free.
• No auth/cookie/CORS/GitHub App/session change (pure function over caller-supplied data).
• MCP behavior added + tested (output schema + schema-valid content).
• No UI changes; no changelog edit.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.10%. Comparing base (48d2a39) to head (df095fd).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5797   +/-   ##
=======================================
  Coverage   95.10%   95.10%           
=======================================
  Files         583      584    +1     
  Lines       46419    46440   +21     
  Branches    14841    14849    +8     
=======================================
+ Hits        44148    44169   +21     
  Misses       1515     1515           
  Partials      756      756           

Flag	Coverage Δ
shard-1	43.75% <80.95%> (+0.01%)	⬆️
shard-2	36.26% <85.71%> (+0.02%)	⬆️
shard-3	32.11% <19.04%> (-0.01%)	⬇️
shard-4	32.85% <19.04%> (-0.01%)	⬇️
shard-5	31.63% <19.04%> (-0.01%)	⬇️
shard-6	44.52% <19.04%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-engine/src/results-payload.ts	100.00% <100.00%> (ø)
src/mcp/server.ts	95.87% <100.00%> (+0.03%)	⬆️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-14 17:22:39 UTC}

6 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a pure `buildResultsPayload` composer in the engine package plus a new MCP tool (`loopover_build_results_payload`) exposing it, with a thin re-export shim in `src/results-payload.ts` mirroring the existing intake-bridge pattern. The logic is straightforward and well-tested: defaults for missing prNumber/changedFiles are handled correctly, the diff preview is properly capped while totals still count every file, and both engine-level and MCP-level tests exercise the null/omitted-PR and truncation branches. The `outputSchema` using `z.unknown().optional()` for `diffPreview`/`totals` is loose but not incorrect since `toolResult` presumably still returns the concrete shape.

Nits — 5 non-blocking

• src/mcp/server.ts:967 hardcodes a `5000` max array length for changedFiles; consider naming it as a constant for clarity.
• src/mcp/server.ts's buildResultsPayloadOutputSchema uses z.unknown().optional() for diffPreview and totals instead of a precise shape, weakening the MCP output-schema contract even though runtime values are correct.
• packages/loopover-engine/src/results-payload.ts hardcodes the github.com PR URL host; fine for now but worth a mental note if enterprise/self-hosted git servers are ever supported.
• The long block comment at the top of results-payload.ts is somewhat verbose for a file whose exports are already well-documented with JSDoc.
• Tighten buildResultsPayloadOutputSchema in src/mcp/server.ts to mirror the concrete ResultsPayload shape (prLink, summary, diffPreview array of {path, additions, deletions}, totals object) instead of z.unknown().

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4801
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 91 registered-repo PR(s), 37 merged, 39 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	luciferlive112116; Gittensor profile; 91 PR(s), 39 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The PR closes a linked issue (#4801) with a small, well-scoped, pure formatting function and its MCP wiring, directly completing the delivery half of the described Rent-a-Loop pipeline.

Linked issue satisfaction

Addressed
The PR adds a pure buildResultsPayload composer plus an MCP tool that turns a completed iteration's metadata into a PR link, plain-language summary, and bounded diff preview, matching the deliverable exactly, and includes engine-level and MCP end-to-end tests demonstrating a correct payload without manual assembly.

Review context

• Author: luciferlive112116
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 91 PR(s), 39 issue(s).
• Related work: Titles/paths share 3 meaningful terms. (issue #4914, issue #4801)
• Related work: Titles/paths share 3 meaningful terms. (issue #4921, issue #4801)
• Related work: Titles/paths share 3 meaningful terms. (issue #4801, issue #4803)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.