feat(integration): add QuantLabTool adapter MVP for local Stepbit execution

[Whiteks1]

Summary

Implement the local Stepbit ↔ QuantLab adapter MVP so Stepbit can invoke QuantLab as a local tool, wait for completion, and consume canonical results through the existing CLI contract.

This issue is only about the local adapter MVP. It is not about distributed execution.

Why this is the next block

QuantLab is now in Stage O — Stepbit Automation Readiness and already exposes the minimum execution surfaces needed for a first adapter:

• main.py --json-request as the machine-to-machine request entrypoint
• optional lifecycle signalling via --signal-file
• canonical run artifacts under outputs/runs/<run_id>/
• canonical machine-facing result data in report.json.machine_contract
• automatic runs_index.csv/json/md refresh after successful run-producing commands

The next useful step is to consume that surface from Stepbit without introducing distributed complexity.

Objective

Create an MVP QuantLabTool adapter in Stepbit that can:

• resolve the correct local QuantLab Python interpreter
• invoke QuantLab via main.py --json-request
• optionally pass --signal-file
• wait for process completion
• load canonical result data from report.json.machine_contract
• return a normalized success/error payload back to Stepbit

Exact scope

Accepted inputs

The adapter should accept at least these request shapes:

command: "run"

params should support the existing CLI/request mapping used by QuantLab for plain runs, including typical fields such as:

• ticker
• start
• end
• interval
• fee
• optional strategy/runtime fields already accepted by QuantLab request parsing

command: "sweep"

params must support the current stable sweep contract:

• config_path as required input
• out_dir or sweep_outdir as optional output location overrides

Invocation contract

The adapter must treat --json-request as the primary invocation surface, for example:

<resolved_python> main.py --json-request '<payload>' --signal-file '<temp_signal_file>'

Output contract

On success, the adapter should return a normalized object sourced from canonical artifacts and completion metadata, including at minimum:

• status
• command
• run_id
• artifacts_path
• report_path
• mode
• summary
• machine_contract

The source of truth for result loading should be report.json.machine_contract, not legacy top-level assumptions.

Signal-file behavior

When --signal-file is provided, the adapter should use it for lifecycle visibility and completion/failure context. Polling-only fallback behavior can exist, but the signal file is the preferred bridge.

In scope

• MVP QuantLabTool / adapter implementation in Stepbit
• support for local run and sweep requests
• local interpreter / venv resolution
• subprocess invocation with explicit interpreter
• optional --signal-file usage
• final result loading from canonical report.json
• consumption of report.json.machine_contract as the normalized result contract
• deterministic surfacing of non-zero exit/failure cases
• basic end-to-end local validation and documentation

Out of scope

• distributed sweeps
• queueing / event-bus orchestration beyond the current signal-file bridge
• dashboard work
• cloud or non-local deployment
• redesign of existing QuantLab contracts

Acceptance criteria

• Stepbit can invoke QuantLab locally for run
• Stepbit can invoke QuantLab locally for sweep
• the adapter uses the project-local interpreter when available
• successful execution returns normalized completion data
• report.json.machine_contract is consumed as the canonical result surface
• failure cases are surfaced deterministically
• an end-to-end local validation path exists and is documented

Related

• follows the completed QuantLab run/output stabilization work
• is the immediate next integration step in Stage O
• must stay smaller in scope than distributed orchestration work in feat(integration): distributed QuantLab sweeps orchestration (post-MVP) #29