feat(mcp): add loopover-mcp agent start CLI subcommand

[michiot05]

Summary

• Closes feat(mcp): add loopover-mcp agent start CLI subcommand mirroring the existing loopover_agent_start_run MCP tool #8314: adds the loopover-mcp agent start CLI subcommand — the human-typable counterpart to the existing loopover_agent_start_run stdio MCP tool, closing the one CLI/MCP parity gap the audit found.
• runAgentCli gains a start branch that POSTs the same /v1/agent/runs request shape the stdio tool sends: { objective, actorLogin, surface, target: { repoFullName?, pullNumber?, issueNumber? } }. objective and actorLogin are non-optional in agentRunShape, so both are enforced (--login resolved via the same options.login ?? LOOPOVER_LOGIN ?? GITHUB_LOGIN pattern as plan/packet; --objective required), throwing a clear usage error when either is missing. --repo/--pull/--issue map to the optional target fields. Output goes through the existing outputAgentPayload helper (--json passthrough vs. summary).
• surface: "cli" (not the stdio tool's "mcp"), per the issue: this keeps the two entry points distinguishable server-side — the stated goal — whereas reusing "mcp" would make them indistinguishable.
• Registered start in CLI_COMMAND_SPEC.agent (so it tab-completes and passes the spec↔handler parity check) and documented it in printAgentHelp.

Tests

• test/unit/mcp-cli-agent-start.test.ts — in-process coverage calling the exported runAgentCli directly (a subprocess-spawned CLI run is invisible to v8/Codecov, so the existing subprocess-based agent tests can't cover a new branch): asserts the exact POST /v1/agent/runs body with surface: "cli" and every target field; the empty-target case; --json passthrough; missing---login, missing---objective, and valueless---objective usage errors; the non-start fall-through; and the help listing. 100% of the changed lines and branches, verified locally via lcov.
• runAgentCli is exported via a separate export { runAgentCli } statement rather than an inline export async function, so the CLI_COMMAND_SPEC↔handler parity test's \n(?:async )?function boundary regex still delimits the handler correctly (an inline export prefix broke that boundary and bled this handler's subcommands into the adjacent runCacheCli's). Added a captured POST /v1/agent/runs route to the CLI test harness.

Scope

• Conventional Commit title; focused; follows CONTRIBUTING.md; no site//CNAME.
• Linked a currently open issue (Closes #8314).

Validation

• git diff --check
• npm run typecheck
• npm run test:coverage locally (100% patch coverage on the changed lines/branches, verified via lcov)
• npm run build:mcp, npm run test:mcp-pack
• npm run command-reference:check, npm run docs:drift-check
• full test/unit/mcp-* suite (861 tests) green, incl. the CLI_COMMAND_SPEC↔handler parity check

If any required check was skipped, explain why:

• This change is confined to packages/loopover-mcp/bin/loopover-mcp.ts plus test files (the CLI harness + the new in-process test). It touches no engine code, API/OpenAPI, migration, generated artifact, UI, or worker surface, so the remaining test:ci steps (engine build/tests, workers, ui:build, db/drift checks) are unaffected. Engine was rebuilt (a stale dist otherwise breaks whole-repo typecheck), typecheck is clean, and the full mcp test surface + mcp-pack + command-reference + docs-drift all pass.

Safety

• No secrets, wallets, hotkeys, trust scores, or reward values anywhere.
• MCP/CLI behavior updated and tested; the new command only enqueues a run (no code/PR/comment write), matching printAgentHelp's existing copilot-only description.

UI Evidence

Not applicable — a CLI subcommand with no visible UI, frontend, docs, or extension change.

Notes

• Additive only: no change to the existing plan/status/explain/packet subcommands or the stdio MCP tool. surface: "cli" is the one deliberate divergence from the mirrored stdio tool, per the issue's distinguishability requirement.

[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 83.20%. Comparing base (2494517) to head (4fe77eb).
⚠️ Report is 11 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8443      +/-   ##
==========================================
- Coverage   92.42%   83.20%   -9.23%     
==========================================
  Files         791       98     -693     
  Lines       79294    24962   -54332     
  Branches    23950     4729   -19221     
==========================================
- Hits        73291    20769   -52522     
+ Misses       4866     3952     -914     
+ Partials     1137      241     -896     

Flag	Coverage Δ
shard-1	12.76% <0.00%> (-45.00%)	⬇️
shard-2	15.07% <0.00%> (-32.61%)	⬇️
shard-3	16.40% <100.00%> (-40.18%)	⬇️

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

Files with missing lines	Coverage Δ
packages/loopover-mcp/bin/loopover-mcp.ts	18.97% <100.00%> (+1.00%)	⬆️

... and 693 files with indirect coverage changes

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-24 13:47:32 UTC}

3 files · 1 AI reviewer · no blockers · readiness 93/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a `agent start` CLI subcommand that POSTs to /v1/agent/runs, mirroring the stdio tool's request shape with `surface: "cli"` to keep the two entry points distinguishable server-side, and registers/documents it consistently in CLI_COMMAND_SPEC and printAgentHelp. The implementation follows the same --login resolution and validation patterns already used by `plan`/`packet`, and the new in-process test suite exercises the full request body (including empty-target and multi-field cases), --json passthrough, and every usage-error path with a real fixture server capturing the POST body — this is real coverage of a real path, not a fabricated scenario. The `export { runAgentCli }` as a separate statement (vs inline `export async function`) is a deliberate, explained accommodation for the CLI_COMMAND_SPEC↔handler parity regex.

Nits — 6 non-blocking

• packages/loopover-mcp/bin/loopover-mcp.ts:4899-4919 — the inline feat(mcp): add loopover-mcp agent start CLI subcommand mirroring the existing loopover_agent_start_run MCP tool #8314 comment block is fairly long for a one-branch addition; the PR description already carries this rationale, so a shorter in-code note would read cleaner per the file's own terse-comment convention elsewhere.
• test/unit/mcp-cli-agent-start.test.ts:25 — the literal `"in-process-token"` value triggered a generic-secret scan; it's clearly a test fixture token, not a real credential, but consider a more scanner-friendly placeholder (e.g. `test-token-placeholder`) to avoid future false positives in secret-scanning CI.
• packages/loopover-mcp/bin/loopover-mcp.ts:4906 — `Array.isArray(options.issue) ? options.issue[0] : options.issue` silently drops all but the first `--issue` value with no warning; worth confirming this matches the existing convention for repeated flags elsewhere (e.g. `--changed-file`) rather than being a one-off silent-drop.
• Consider trimming the multi-paragraph inline comments at packages/loopover-mcp/bin/loopover-mcp.ts:4899 and :4968 down to a single line each, since the full rationale already lives in the PR description and the file's own convention (per its header comment) favors terse WHY-only notes.
• In test/unit/mcp-cli-agent-start.test.ts, swap the `"in-process-token"` fixture string for a name that can't be flagged by automated secret scanners, e.g. `fixture-auth-token`.
• Possible secret-shaped assignment in the diff (generic_secret_assignment) — Verify the value is not a real credential.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#8314
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low 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: 33 registered-repo PR(s), 16 merged, 6 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	michiot05; Gittensor profile; 33 PR(s), 6 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds a `start` branch to runAgentCli that POSTs the same request shape as the stdio tool with surface "cli", enforces --login/--objective errors, maps --repo/--pull/--issue to target fields, routes output through outputAgentPayload, registers it in CLI_COMMAND_SPEC and printAgentHelp, and includes a dedicated unit test covering the success, empty-target, --json, missing-login/objective, a

Review context

• Author: michiot05
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Rust
• Official Gittensor activity: 33 PR(s), 6 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Triage stale or unlinked PRs.

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.

🧪 Chat with LoopOver

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

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

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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]

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