feat(mcp): migrate the stdio MCP server's 102 tools to @loopover/contract (#9537) (#9565)

* feat(contract): add the stdio server's local-git tool contracts and converge the hand-mirrored inputs

Adds the 19 tools the remote migration could not cover, which is every tool
the stdio server registers that the remote one either does not have or
declares differently. All 102 stdio tools now have a contract entry.

Thirteen of these existed on both servers with two hand-mirrored input
schemas that had already drifted -- the stdio copies of find_opportunities,
retrieve_issue_context and mark_notifications_read carried no length bounds
at all. The contract takes the wider bound in every such case, and resolves
the eligibility-transform question #9518 documented rather than solved: the
contract describes what a caller may SEND, so the pre-transform shape is the
one that belongs here and the remote server's downgrade stays a server-side
control over the parsed value.

* feat(mcp): register every stdio tool from @loopover/contract

All 102 stdio tools now take their title, description, category, annotations,
and BOTH schemas from the registry. ~85 hand-mirrored input shapes and the
560-line STDIO_TOOL_DESCRIPTORS table are gone (the bin file drops ~1,100
lines), every handler is typed via z.infer instead of `(input: any)`, and 97
of the 102 gain a real output schema where they had none.

The registration helper passes the schema OBJECTS, not their .shape. The SDK
accepts either, but a raw shape is re-wrapped in a plain z.object, which
discards the catchall -- so every output modelled as a looseObject would be
advertised and enforced as additionalProperties:false, and any field the
payload carries beyond the modelled set becomes a -32602 the caller cannot act
on.

Turning the output schemas on surfaced six real defects, which is what they are
for:

- the agent audit feed models pullNumber/actor/detail as nullable, but the
  route OMITS them rather than sending null, so every real feed failed
  validation;
- plan_repo_issues and generate_contributor_issue_drafts declared their six
  counters required, but the service short-circuits to a countless
  disabled/unavailable posture -- which is exactly why the CLI proxies carry
  '?? 0' fallbacks;
- three test fixtures described payloads the services do not produce (laneFit
  as a lane name rather than a fit score, autoMaintain as a string rather than
  the settings object, a pending-action row missing four ledger columns).
  Fixtures fixed, not schemas.

Four input divergences converged, each by widening so no live caller breaks:
get_repo_onboarding_pack gains stdio's 'refresh'; preflight_local_diff and
explain_score_breakdown gain stdio's local-diff fields; and
get_pr_ai_review_findings -- the one tool whose two servers disagreed on a
FIELD NAME -- accepts both 'number' (canonical, and what every other PR-scoped
tool uses) and 'pullNumber' (the remote's alias).

list_pending_actions is the single deliberate narrowing: its route hardcodes
status 'pending' and cannot honour a filter, so the stdio server registers
ListPendingActionsStdioInput -- derived from the contract entry with .omit() --
rather than advertising a filter that would silently do nothing.

Also restores .strict() on callerBranchEligibilitySchema, dropped when it was
relocated in #9518: both servers wrapped it strictly before the migration, and
without it a caller inventing an eligibility field is silently stripped instead
of rejected.

* fix(ci): stop import-specifiers:check reporting three false positives and one real miss

The checker exits 1 on main today. Two of the three reports are its own false
positives and the third is mine.

- check-dead-source-files-script.test.ts embeds import-statement TEXT as string
  fixtures for its script's injectable readFile, and a js-suffixed relative
  specifier is the exact case that test exists to pin -- so its fixtures read as
  violations. Allowlisted, the same way this checker already allowlists its own
  test file for the same reason.
- scripts/actionlint.ts runs under 'node --experimental-strip-types', whose
  loader does no extension resolution: the literal .ts is the only form that
  starts. That is a fact about how package.json invokes it, not something
  readable from the source, so the entrypoint is listed explicitly.
- The three relative imports #9517/#9518 added to contract-registry.test.ts
  carried .js in a Bundler-resolved zone. Extension dropped.

* feat(engine): collapse the duplicated plan-DAG state machine into @loopover/engine

Completes #9537's last requirement, and fixes the build failure the first push
of PR #9565 hit.

THE BUILD FIX: `ToolContract` was imported from @loopover/contract/tools, which
only imports that type internally and never re-exports it. The local typecheck
resolves the package through a src alias and passed; the real package build
resolves the export map and failed at 'Build MCP'. Now imported from the package
root, which does export it.

THE PLAN-DAG DEDUP: buildPlanDag/validatePlanDag/the step state machine existed
in src/services/plan-dag.ts AND hand-copied, untyped, into the stdio MCP bin --
whose own comment explained why: it resolves @loopover/engine through the
published package, whose export map did not surface them. It does now.

Moving it turned up a THIRD partial copy already in the engine: plan-export.ts
holds the step/plan types, plan-step-readiness.ts holds nextReadySteps/isDone,
and plan-overall-status.ts holds the status vocabulary, each decomposed into its
own module. The moved file imports all three rather than restating them -- a
fourth PlanDag would have defeated the point -- and contributes only the
mutating half (build, validate, advance) that had no engine home.

src/services/plan-dag.ts stays as the Worker's import path, now a re-export, so
nothing else had to move.

Release ordering, which is why this looked blocked: both publish workflows are
workflow_dispatch-only, so nothing auto-publishes on merge and an operator
publishes the engine before the CLI, as usual. The engine takes a minor bump for
the new export, with packages/loopover-miner/expected-engine.version and both
consumers' dependency ranges moved to ^3.16.0 in the same commit so a published
CLI can never resolve an engine without it.

Also declares @loopover/contract#build as an edge of the root typecheck task.
That was working only because ci.yml happens to run a contract build first; the
edge makes a bare 'turbo run typecheck' correct on its own.

* fix(mcp,typecheck): prune the imports the contract migration orphaned, and make the root typecheck catch them

The stdio migration left ~40 imports and shape constants unreferenced once every
tool started resolving its schemas through getToolContract. @loopover/mcp's own
tsconfig sets noUnusedLocals, so its package build failed on all of them -- twice
-- while 'npm run typecheck' and the full unit suite stayed green locally.

That gap is the real bug, and it is fixed here rather than worked around: the
root 'typecheck' script now runs the root tsconfig AND each package whose config
is stricter than it (@loopover/contract, @loopover/mcp, @loopover/miner). A bare
'npm run typecheck' now covers the same surface CI's build steps do, so this
class of failure cannot pass locally and fail in CI again.

Also defaults preflight_local_diff's baseRef at the call site. It is optional in
the shared contract input -- the remote server has no checkout to read -- so the
local diff collector needs the 'HEAD' default the stdio-only shape used to bake
into the schema.

* chore(release): sync the release-please manifest to the engine's 3.16.0 bump

The engine version bump that gives the stdio server a published plan-DAG export
has to be reflected in .release-please-manifest.json, which release-please reads
to decide what it is releasing. Caught by release-manifest:sync:check.

* test(mcp): cover the pr-ai-review-findings field-name alias and its two caller-error paths

codecov/patch flagged the new branches in getPrAiReviewFindings: every existing
test supplies pullNumber, so the canonical 'number' side of the alias and both
'required field missing' throws were unexercised.

* chore: move the #9520 validator files out of this PR

They were swept in by a git add -A while both branches were in flight; they
belong to the contract-validator issue, not the stdio migration.

* test(engine): move the plan-DAG behavioural tests in with the implementation

codecov/patch flagged packages/loopover-engine/src/plan-dag.ts at 40%: the engine
uploads its own coverage from its own node:test suite, so the root suite's
test/unit/plan-dag.test.ts -- which exercises the same code thoroughly through
the Worker's re-export -- contributes nothing to it.

The tests move with the implementation. 100% statements and branches on the
moved module, verified with c8 against the engine's own dist.

Author: JSONbored

.release-please-manifest.json

@@ -1,6 +1,6 @@
 {
   "packages/loopover-mcp": "3.15.2",
-  "packages/loopover-engine": "3.15.3",
+  "packages/loopover-engine": "3.16.0",
   "packages/loopover-miner": "3.15.2",
   "packages/loopover-ui-kit": "1.2.0"
 }

package-lock.json

@@ -97,7 +97,9 @@
     "changelog:check:mcp": "node --experimental-strip-types scripts/check-changelog.ts --mcp",
     "mcp:release-due": "tsx scripts/check-mcp-release-due.ts --json",
     "mcp:release-candidate": "tsx scripts/check-mcp-release-candidate.ts",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "npm run typecheck:root && npm run typecheck:packages",
+    "typecheck:root": "tsc --noEmit",
+    "typecheck:packages": "tsc -p packages/loopover-contract/tsconfig.json --noEmit && tsc -p packages/loopover-mcp/tsconfig.json --noEmit && tsc -p packages/loopover-miner/tsconfig.json --noEmit",
     "check-node-version": "node --experimental-strip-types scripts/check-node-version.ts",
     "pretest": "npm run check-node-version",
     "test": "vitest run",

package.json

@@ -598,6 +598,17 @@ export const ListPendingActionsOutput = z.looseObject({
   status: z.string().optional(),
   pendingActions: z.array(pendingActionEntrySchema).optional(),
 });
+/**
+ * The stdio server's narrowed variant, DERIVED rather than restated.
+ *
+ * `GET /agent/pending-actions` takes no query parameters and hardcodes status "pending", so the
+ * stdio server cannot honour the filter its remote counterpart offers. An agent reads the published
+ * schema to decide what to send, so advertising a filter that silently does nothing is worse than
+ * not advertising it -- this is the one place in the migration where a server deliberately serves
+ * LESS than the contract, and it says so in code rather than by omission.
+ */
+export const ListPendingActionsStdioInput = ListPendingActionsInput.omit({ status: true });
+
 export const listPendingActionsTool = defineTool({
   name: "loopover_list_pending_actions",
   title: "List pending actions",
@@ -644,12 +655,15 @@ export const GetAgentAuditFeedOutput = z.looseObject({
   repoFullName: z.string().optional(),
   events: z
     .array(
+      // `.nullish()`, not `.nullable()`: the REST route this proxies OMITS these for an event that
+      // has none rather than sending an explicit null, and modelling them as merely nullable made
+      // every real audit feed fail output validation (#9537).
       z.looseObject({
         eventType: z.string(),
-        pullNumber: z.number().nullable(),
+        pullNumber: z.number().nullish(),
         outcome: z.string(),
-        actor: z.string().nullable(),
-        detail: z.string().nullable(),
+        actor: z.string().nullish(),
+        detail: z.string().nullish(),
         createdAt: z.string(),
       }),
     )

packages/loopover-contract/src/tools/agent.ts

@@ -49,6 +49,10 @@ const validationEntrySchema = z.strictObject({
 // ── preflight local diff (input + output: no transform) ─────────────────────────────────────────
 
 export const PreflightLocalDiffInput = PreflightPrInput.extend({
+  // #9537: `cwd`/`baseRef` name a checkout only the stdio server can read; the remote server
+  // ignores them. Widening the shared input is the safe direction.
+  cwd: z.string().optional(),
+  baseRef: z.string().optional(),
   changedLineCount: z.number().int().min(0).optional(),
   testFiles: z.array(z.string().max(PREFLIGHT_LIMITS.changedFileChars)).max(PREFLIGHT_LIMITS.changedFiles).optional(),
   commitMessage: z.string().max(PREFLIGHT_LIMITS.bodyChars).optional(),

packages/loopover-contract/src/tools/branch.ts

@@ -484,12 +484,46 @@ export const validateConfigTool = defineTool({
   output: ValidateConfigOutput,
 });
 
-export const LocalStatusInput = noInput;
+/**
+ * A THIRD divergence, found while migrating the stdio server (#9537) -- one the issue did not name,
+ * because it is not a payload that drifted but two different tools that collided on one name:
+ *
+ *  - the remote server answers "what does this MCP endpoint support" (reachability, the supported
+ *    endpoint, the tool surface it advertises);
+ *  - the stdio server answers "what is the state of THIS CLI on THIS machine" (api url, package
+ *    version, token/session presence, workspace roots, and the local git checkout).
+ *
+ * Neither can answer the other's question -- the remote has no checkout to inspect, and the CLI has
+ * no endpoint surface to report -- so unlike get_repo_context and get_pr_reviewability there is no
+ * payload to converge on. The real fix is a rename, which breaks every caller of whichever side
+ * loses the name, so it is filed rather than done in flight. The union below keeps both wires
+ * working, gives both a validated schema instead of none, and keeps the collision visible.
+ *
+ * `cwd`/`baseRef`/`repoFullName` on the input are the stdio side's; the remote server ignores them.
+ * Widening an input is always the safe direction.
+ */
+export const LocalStatusInput = z.object({
+  cwd: z.string().optional(),
+  baseRef: z.string().optional(),
+  repoFullName: z.string().min(3).optional(),
+});
 export const LocalStatusOutput = z.looseObject({
+  // Remote fields.
   apiAvailable: z.boolean().optional(),
-  sourceUploadDefault: z.boolean().optional(),
   supportedEndpoint: z.string().optional(),
   supportedTools: z.unknown().optional(),
+  // Shared.
+  sourceUploadDefault: z.boolean().optional(),
+  // stdio fields.
+  apiUrl: z.string().optional(),
+  package: z.looseObject({ name: z.string(), version: z.string() }).optional(),
+  hasToken: z.boolean().optional(),
+  profile: z.record(z.string(), z.unknown()).optional(),
+  authLogin: z.string().nullable().optional(),
+  sessionExpiresAt: z.string().nullable().optional(),
+  sourceUploadSupported: z.boolean().optional(),
+  workspaceRoots: z.unknown().optional(),
+  git: z.record(z.string(), z.unknown()).optional(),
 });
 export const localStatusTool = defineTool({
   name: "loopover_local_status",

packages/loopover-contract/src/tools/discovery-utility.ts

@@ -116,6 +116,27 @@ import {
   agentStartRunTool,
   agentGetRunTool,
 } from "./agent.js";
+import {
+  preflightCurrentBranchTool,
+  previewCurrentBranchScoreTool,
+  rankLocalNextActionsTool,
+  explainLocalBlockersTool,
+  remediationPlanTool,
+  preparePrPacketTool,
+  agentPreparePrPacketTool,
+  reviewPrBeforePushTool,
+  draftPrBodyTool,
+  compareLocalVariantsTool,
+  previewLocalPrScoreTool,
+  getEligibilityPlanTool,
+  comparePrVariantsTool,
+  feasibilityGateTool,
+  markNotificationsReadTool,
+  watchIssuesTool,
+  findOpportunitiesTool,
+  retrieveIssueContextTool,
+  simulateOpenPrPressureTool,
+} from "./local-branch.js";
 
 /**
  * #9517's pilot batch, the full AMS miner server (#9536, all 11 tools), and the remote server's
@@ -218,6 +239,25 @@ export const TOOL_CONTRACTS: readonly ToolContract[] = [
   agentExplainNextActionTool,
   agentStartRunTool,
   agentGetRunTool,
+  preflightCurrentBranchTool,
+  previewCurrentBranchScoreTool,
+  rankLocalNextActionsTool,
+  explainLocalBlockersTool,
+  remediationPlanTool,
+  preparePrPacketTool,
+  agentPreparePrPacketTool,
+  reviewPrBeforePushTool,
+  draftPrBodyTool,
+  compareLocalVariantsTool,
+  previewLocalPrScoreTool,
+  getEligibilityPlanTool,
+  comparePrVariantsTool,
+  feasibilityGateTool,
+  markNotificationsReadTool,
+  watchIssuesTool,
+  findOpportunitiesTool,
+  retrieveIssueContextTool,
+  simulateOpenPrPressureTool,
   minerPingTool,
   minerPortfolioDashboardTool,
   minerManageStatusTool,
@@ -259,4 +299,5 @@ export * from "./review.js";
 export * from "./branch.js";
 export * from "./discovery-utility.js";
 export * from "./agent.js";
+export * from "./local-branch.js";
 export * from "./miner.js";