[faranm-stack]

Summary

Fixes the two integration issues from the microsoft#162 review and a range-check bug found while testing real instrument files. The agent now calls a single flow_qc_utils.run_qc(fcs_path, output_dir) function, and the flow-qc launcher exits with Python's status. The declared-range check now counts events at the instrument maximum ($PnR - 1).

Type of change

• New agent (under agents/<name>/)
• Update to an existing agent
• New starter kit (under starter-kits/<name>/)
• Update to an existing starter kit
• Schema change (docs/schemas/**)
• Workflow / script change (.github/**)
• Documentation only
• Other (describe below)

Related issue / tracking

Refs microsoft#162

Schema impact

• No schema changes
• Schema changes are backward compatible
• Schema changes are breaking — add the breaking-change label and link the rollout plan below

Validation checklist

• Documentation (README.md, schemas) is updated to match the change.
• No hand-edits to .auto-registry/** (it is generated post-merge).
• No OS / editor artefacts committed (.DS_Store, .env, *.swp, .idea/, .vs/, etc.).
• If model-weight files are added, they are Git-LFS tracked, ≤5 GB each, and in an allowed format. (None added.)
• No secrets, customer data, or internal-only URLs are committed.
• All Markdown links resolve.

Reviewer notes (optional)

Changes (3 commits)

• eee9b32: new run_qc loads one FCS file and writes <stem>_qc_report.json, <stem>_channel_summary.csv and <stem>_dashboard.png. A file with no events raises a clear ValueError. agent.yaml shows the exact call, and tool.yaml keeps Python's exit status (_EXIT=$? / exit $_EXIT, as in cp2k).
• 582001d: pins the six Python packages in the Dockerfile to the versions tested here (FlowIO 1.4.0, Matplotlib 3.11.2, NumPy 2.5.4, pandas 3.1.0, scikit-learn 1.9.1, SciPy 1.18.1).
• a713475: the declared-range fraction compared values with $PnR, but $PnR counts the possible values, so instruments record their maximum as $PnR - 1. It now counts values at or above $PnR - 1. The dashboard samples events evenly across the whole run instead of plotting only the first 20,000. The README documents raw values and the file types the tool rejects.

Validation (fork CI run on a713475)

• Tool tests with the pinned packages: 9 passed. The launcher tests fail against the original tool.yaml (exit 0 instead of 1 and 3).
• Built image: the documented run_qc snippet writes the JSON, CSV and PNG for a 100-event synthetic FCS (FITC-A median 50.5). The script the agent generated in Studio on Oct 7 now exits 1 with its TypeError. A zero-event FCS exits 1 with "contains no events".
• Six public instrument files from FlowIO's sample data (BSD-3-Clause, downloaded at run time): all processed, with event counts matching FlowIO. Before a713475, the range fraction was 0 for every channel; for example, 782 SSC-H events sit at 1023 in 3FITC_4PE_004.fcs, and 247 SSC-A events sit at the maximum in G11.fcs. It now matches the count at $PnR - 1 on every channel.
• python .github/scripts/validate_pr.py on all agents/flow-cytometry-referee files: passed.
• Discovery Studio (PRValidation), with an agent and tool built from this branch: a fresh agent-led run on the a713475 image, with the same prompt and file as the failed Oct 7 run, called only run_qc. It reported 100 events and FITC-A median 50.5, and shared the outputs. A deliberately failing script shows as a failed run (exit code 1); tool.yaml has not changed since that test.

Not covered

• Files with several data sets (such as Beckman Coulter LMD) and files whose HEADER and TEXT give different DATA offsets fail with a clear error; this is now documented.
• The present_valid and acquisition-rate CV questions from the review are unchanged; those decisions are yours.